Prewave Users API
🆕 NEW - API to manage users in the public network. Available from February 2026.
OpenAPI Specification
openapi: 3.0.1
info:
title: Public Prewave Actions Users API
description: 'Documentation of the Public Prewave API.
## What''s New
### Q1 2026 — Supplier Management, User Management, Actions and Feed
This quarter introduces major v2 upgrades, expanded administrative capabilities, and the new Actions API.
- **Core Releases:** Deployed Supplier Management API v2 and Feed API v2, alongside the all-new Actions API.
- **Enhanced Functionality:** Added robust identifier management, granular user and role configuration, and endpoints for managing supplier connection contacts.
- ⚠️ **Required Migration:** Legacy v1 endpoints for Suppliers and Sites Upsert have been deprecated. Developers must migrate existing integrations to v2 by **May 31, 2027** (original deadline was December 31, 2026).
📖 **[Read the Q1 2026 changelog](https://docs.prewave.com/en/articles/699847-q1-2026-public-api-updates)**
### Q2 2026 — Supplier Screening and External Scores
We have expanded our v2 documentation to include comprehensive integration guidance for supplier screening and validation workflows and identifier-based external score ingestion.
- **New Capabilities:** Added support for optional post-onboarding screening and validation during the create event.
- **External Scores:** Batch POST for multiple supplier sites, per-site history GET, and event-type discovery GET (`/public/v1/scores/externals` and `/public/v1/scores/externals/event-types`). Documented in OpenAPI when enabled for your organization.
- **Developer Resources:** Published new integration examples and detailed identifier validation rules to streamline your implementation process.
📖 **[Read the Q2 2026 changelog](https://docs.prewave.com/en/articles/699849-q2-2026-public-api-updates)**
### Q3 2026 — Scores Webhooks
To support event-driven architectures and eliminate the need for continuous API polling, we are introducing webhooks for score state changes later this year.
- **Event-Driven Architecture:** Register webhook URLs to receive real-time HTTP payloads whenever a supplier''s score updates, so you can drive immediate mitigation responses without polling the API.
- **Availability:** Comprehensive OpenAPI specifications and payload schemas will be published closer to the release date.
- **Note:** Schemas and behaviors are subject to refinement prior to general availability.
Documentation updates will be provided prior to release.
### Q4 2026 — Feed V2
We are enhancing Feed API v2 with additional capabilities on top of the existing `GET /public/v2/feed` contract (see Q1 changelog and OpenAPI for the current Feed v2 integration).
- **Availability:** Details will be announced before release.
- **Note:** Schemas and behaviors are subject to refinement prior to the official release.
Documentation updates will be provided prior to release.
---
## Authentication
Prewave’s public api uses *API tokens* to authenticate against our RESTful service. We’ll provide you an *API-token* that each
endpoint needs present as a http header.
To pass the token in a request, simply add it as a header-parameter with
* key = X-Auth-Token
* value = api-token
See an example in curl below where the api-token would be 12345678-90ab-cdef-1234-567890abcdef
```
curl --request GET \
--url https://REPLACE_WITH_SERVER/public/v1/target/prewave/3975230/alerts \
--header ''X-Auth-Token: 12345678-90ab-cdef-1234-567890abcdef''
```
---
## Manage API Tokens
Before you can obtain your API token, you''ll need the credentials for your API user. These credentials will be
sent to you as part of the company-onboarding. If you haven''t got your credentials yet, please reach out to
your sales-contact at Prewave or contact us via info@prewave.ai
To generate an API Token, navigate to https://www.prewave.com/management/api and log in with the
credentials of your API user. Then click at the button "Create New" and use your new api-token authentication as a header parameter.
You can create multiple API tokens and also remove existing API tokens on https://www.prewave.com/management/api.
API tokens do not expire, therefore you have to maintain the list of API tokens you are using manually.
---
## Default Rate Limits
We have two types of default rate limits. For increased access, please contact customer success.
| Type | Requests per 10 seconds | Requests per Minute |
|-----------------------------------|-------------------------|---------------------|
| GET requests | 100 | 500 |
| POST, PUT, PATCH, DELETE requests | 20 | 100 |
'
version: '1.0'
servers:
- url: https://api.prewave.com
description: Production Environment
security:
- Token authentication: []
tags:
- name: Users
description: 🆕 NEW - API to manage users in the public network. Available from February 2026.
paths:
/public/v1/users:
get:
tags:
- Users
summary: Search and list users
description: "\n### Overview\nRetrieve a comprehensive list of all users within your customer's scope. This endpoint is ideal for auditing, synchronization, or building user-management dashboards.\n\n### Use Cases\n- **Auditing**: Regularly export user lists to verify access levels.\n- **Synchronization**: Keep an external user directory in sync with Prewave.\n- **Management**: Build custom internal dashboards for your organization.\n\n### Filtering\nRefine your results using the following optional parameters:\n- **Search**: Matches against name or email (fuzzy matching).\n- **Active**: Filter by account status (active/deactivated).\n- **Confirmed**: Filter by whether the user has verified their account via email.\n\n### Pagination\nThis endpoint returns a paginated result. You can control the page size and offset using the `page` and `size` parameters.\n- **Default Size**: 100\n- **Max Size**: 1000\n\n ### Related Operations\n - **Retrieve Detail**: [GET /public/v1/users/{userId}](#operations-Users-getById)\n - **Onboard User**: [POST /public/v1/users](#operations-Users-create)\n - **Manage Roles**: [GET /public/v1/users/{userId}/roles](#operations-Users_-_Roles-read)\n - **Update User**: [PATCH /public/v1/users/{userId}](#operations-Users-update)\n\n### Required Permission\n`access_public_users`\n "
operationId: get
parameters:
- name: search
in: query
description: Fuzzy search against **first name**, **last name**, or **email**.
required: false
schema:
type: string
example: john
- name: active
in: query
description: Filter by account status. `true` for active users, `false` for deactivated ones.
required: false
schema:
type: boolean
example: true
- name: confirmed
in: query
description: Filter by confirmation status. `true` for users who have verified their email.
required: false
schema:
type: boolean
example: false
- name: page
in: query
description: Zero-based page index (0..N)
required: false
schema:
minimum: 0
type: integer
default: 0
- name: size
in: query
description: The size of the page to be returned
required: false
schema:
minimum: 1
type: integer
default: 100
responses:
'200':
description: Successfully retrieved the paginated list of users.
content:
application/json:
schema:
type: object
properties:
content:
type: array
items:
$ref: '#/components/schemas/PublicUserResponse'
size:
type: integer
format: int32
number:
type: integer
format: int32
totalElements:
type: integer
format: int32
totalPages:
type: integer
format: int32
numberOfElements:
type: integer
format: int32
first:
type: boolean
last:
type: boolean
empty:
type: boolean
examples:
Paginated User List:
summary: Example of a successful paginated response
description: Paginated User List
value: '{"content":[{"id":123,"active":true,"confirmed":true,"firstname":"John","lastname":"Doe","email":"john.doe@company.com","customer":{"id":8797983,"name":"Prewave"},"organization":{"id":64573456,"name":"Prewave"},"plan":{"id":34345453,"name":"Admin","validFrom":1614616305.000000000},"teams":[],"roles":[{"id":1829,"name":"GRANT_USER_MANAGER_ACCESS","description":null}]}],"totalElements":1,"totalPages":1,"size":500,"number":0,"numberOfElements":1,"first":true,"last":true,"empty":false}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 100,\n \"requestCount\": 100,\n \"limits\": [\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 500,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
post:
tags:
- Users
summary: Invite and onboard a new user
description: "\n### Overview\nOnboard a new member to your organization. This action triggers an automated invitation email.\n\n### Use Cases\n- **New Employee**: Onboard a new team member with their required access level.\n- **External Partner**: Invite a stakeholder to collaborate with specific roles.\n- **Automation**: Programmatically create users as part of your internal onboarding flow.\n\n### Invitation Lifecycle\n1. **Request**: You provide the user's email and initial configuration.\n2. **Created**: The user account is initialized with `confirmed: false`.\n3. **Activation**: The user receives an email to set their password and log in.\n4. **Completion**: Once logged in, the user's status changes to `confirmed: true`.\n\n### Workflow Tip\n- Use the `Location` header in the response to immediately access the new user's resource URI.\n- You can pre-assign **teams** and **roles** during the invitation to ensure the user has access from their first login.\n\n### Related Operations\n- **List Users**: [GET /public/v1/users](#operations-Users-get)\n- **Discover Roles**: [GET /public/v1/users/roles/available](#operations-Users_-_Roles-getAvailableRoles)\n- **Assign Roles**: [POST /public/v1/users/{userId}/roles](#operations-Users_-_Roles-add)\n\n### Required Permission\n`manage_public_users`\n "
operationId: invite
requestBody:
description: User configuration for invitation.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCreateUserRequest'
examples:
Basic Invitation:
summary: Minimum required data to invite a user
description: Basic Invitation
value: '{"email":"new.user@company.com","firstname":"New","lastname":"User","teamIds":[1,2],"roleNames":["ROLE_USER_MANAGER"],"planId":5}'
required: true
responses:
'201':
description: Created - Invitation sent successfully. See Location header.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUserResponse'
examples:
Created User Response:
description: Created User Response
value: '{"id":4523345,"active":true,"confirmed":false,"firstname":"New","lastname":"User","email":"new.user@company.ai","customer":{"id":8797983,"name":"Prewave"},"organization":{"id":64573456,"name":"Prewave"},"plan":{"id":5,"name":"Admin","validFrom":1614616305.000000000},"teams":[],"roles":[{"id":1829,"name":"ROLE_USER_MANAGER","description":null}]}'
'400':
description: Bad Request - Validation error (e.g., invalid email format).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Validation Error:
description: Validation Error
value: '{"code":"invalid_request","message":"Email must be a valid email address."}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 20,\n \"requestCount\": 20,\n \"limits\": [\n {\n \"requestLimit\": 20,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
/public/v1/users/{userId}:
get:
tags:
- Users
summary: Retrieve detailed user profile
description: "\n### Overview\nFetch the complete profile of a specific user. This includes organizational details, active subscriptions (plans), and assigned access controls.\n\n### Use Cases\n- **Profile Inspection**: Verify the current configuration of a specific user.\n- **Pre-Update Check**: Retrieve the current state before performing a partial update.\n- **Identity Verification**: Confirm the email and name associated with a numerical ID.\n\n### Identification\nThe `{userId}` is a unique numerical identifier.\n\n### Getting User ID\n- To find users and their numerical IDs, use the Users Management API:\n - `GET /public/v1/users` - Retrieve all users with their `id` field.\n- The `id` field in the user response is the `{userId}` used in this endpoint's path parameter.\n\n ### Related Operations\n - **Update Profile**: [PATCH /public/v1/users/{userId}](#operations-Users-update)\n - **Manage Roles**: [POST /public/v1/users/{userId}/roles](#operations-Users_-_Roles-add)\n\n### Required Permission\n`access_public_users`\n "
operationId: getById
parameters:
- name: userId
in: path
description: The unique numerical identifier of the target user. If you do not have this ID, you can find it by searching for the user via `GET /public/v1/users`.
required: true
schema:
type: integer
format: int32
example: 4523345
responses:
'200':
description: User details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUserResponse'
examples:
Full User Profile:
description: Full User Profile
value: '{"id":4523345,"active":true,"confirmed":true,"firstname":"Max","lastname":"Mustermann","email":"max.mustermann@prewave.ai","customer":{"id":8797983,"name":"Prewave"},"organization":{"id":64573456,"name":"Prewave"},"plan":{"id":34345453,"name":"Admin","validFrom":1614616305.000000000},"teams":[],"roles":[{"id":1829,"name":"ROLE_USER_MANAGER","description":null},{"id":98790,"name":"GRANT_TEAM_MANAGER_ACCESS","description":null}]}'
'404':
description: Not Found - User not found or outside organization scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
User Not Found:
description: User Not Found
value: '{"code":"user_not_found","message":"User with ID 4523345 could not be found."}'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 100,\n \"requestCount\": 100,\n \"limits\": [\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 500,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
patch:
tags:
- Users
summary: Update user profile and status
description: "\n### Overview\nModify profile details, subscription levels, or account status for an existing user.\n\n### Use Cases\n- **Profile Correction**: Correct a user's name or contact details.\n- **Plan Management**: Upgrade or downgrade a user's subscription (e.g., Enterprise vs. Basic).\n- **Status Management**: Activate or deactivate user access.\n- **Access Refinement**: Update team associations.\n\n### Identification\nThe `{userId}` is a unique numerical identifier.\n\n### Getting User ID\n- To find users and their numerical IDs, use the Users Management API:\n - `GET /public/v1/users` - Retrieve all users with their `id` field.\n- The `id` field in the user response is the `{userId}` used in this endpoint's path parameter.\n\n### Partial Updates\nThis endpoint supports **partial updates**. Only the fields provided in the request body will be changed; omitted fields and fields set to null will retain their current values.\n\n### Related Operations\n- **Get Detail**: [GET /public/v1/users/{userId}](#operations-Users-getById)\n- **Manage Roles**: [POST /public/v1/users/{userId}/roles](#operations-Users_-_Roles-add)\n\n### Required Permission\n`manage_public_users`\n "
operationId: update
parameters:
- name: userId
in: path
description: The unique numerical identifier of the target user. If you do not have this ID, you can find it by searching for the user via `GET /public/v1/users`.
required: true
schema:
type: integer
format: int32
example: 4523345
requestBody:
description: Fields to update. Omit fields to keep current values.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUpdateUserRequest'
examples:
Profile, Plan & Status Update:
summary: Update multiple fields including status
description: Profile, Plan & Status Update
value: '{"firstname":"Updated","lastname":"User","planId":1234,"active":true}'
Deactivate User:
summary: Disable user access
description: Deactivate User
value: '{"firstname":null,"lastname":null,"planId":null,"active":false}'
required: true
responses:
'200':
description: User profile and status successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicUserResponse'
examples:
Updated User Profile:
description: Updated User Profile
value: '{"id":4523345,"active":true,"confirmed":true,"firstname":"Updated","lastname":"User","email":"user@company.ai","customer":{"id":8797983,"name":"Prewave"},"organization":{"id":64573456,"name":"Prewave"},"plan":{"id":1234,"name":"Enterprise","validFrom":1614616305.000000000},"teams":[],"roles":[]}'
'404':
description: Not Found - The specified user does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
'403':
description: '403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.'
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedErrorDTO'
examples:
Access denied example:
summary: User lacks necessary permissions or authentication
value: "{\n \"loggedIn\": true,\n \"code\": \"access_denied\",\n \"message\": \"Access denied: you don't have necessary permissions to access this resource\",\n \"solution\": \"Contact support for appropriate permissions\"\n }"
'500':
description: 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Error - Server Error:
summary: Unexpected server error
value: "{\n \"code\": \"internal_error\",\n \"message\": \"An unexpected error occurred\",\n \"solution\": \"Please try again later or contact support\"\n }"
'429':
description: '429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitResponse'
examples:
Rate limit exceeded example:
summary: API rate limit exceeded
value: "{\n \"error\": \"API rate limit exceeded\",\n \"message\": \"You have reached the maximum allowed requests. Please try again later or upgrade your plan for increased access\",\n \"requestLimit\": 20,\n \"requestCount\": 20,\n \"limits\": [\n {\n \"requestLimit\": 20,\n \"timeInSeconds\": 10\n },\n {\n \"requestLimit\": 100,\n \"timeInSeconds\": 60\n }\n ],\n \"currentTime\": \"2026-01-15T10:30:00\",\n \"nextResetAt\": \"2026-01-15T10:30:10\"\n }"
components:
schemas:
PublicUserResponseTeamDTO:
required:
- id
- name
type: object
properties:
id:
type: integer
format: int32
example: null
name:
type: string
example: null
example: null
PublicUserResponseOrganizationDTO:
required:
- id
- name
type: object
properties:
id:
type: integer
format: int32
example: null
name:
type: string
example: null
example: null
PublicUserResponseCustomerDTO:
required:
- id
- name
type: object
properties:
id:
type: integer
format: int32
example: null
name:
type: string
example: null
example: null
PublicUserRoleDTO:
required:
- id
- name
type: object
properties:
id:
type: integer
format: int32
example: null
name:
type: string
example: null
description:
type: string
nullable: true
example: null
example: null
ErrorDTO:
required:
- code
- message
type: object
properties:
code:
type: string
description: Error code
example: null
message:
type: string
description: Error message
example: null
solution:
type: string
description: Possible solution to the error
nullable: true
example: null
description: Error response
example: null
AccessDeniedErrorDTO:
required:
- code
- loggedIn
- message
type: object
properties:
loggedIn:
type: boolean
example: null
permission:
type: string
nullable: true
example: null
code:
type: string
description: Error code
example: null
message:
type: string
description: Error message
example: null
solution:
type: string
description: Possible solution to the error
nullable: true
example: null
example: null
PublicUserResponse:
required:
- active
- confirmed
- customer
- id
- roles
- teams
type: object
properties:
id:
type: integer
format: int32
example: null
active:
type: boolean
example: null
confirmed:
type: boolean
example: null
firstname:
type: string
nullable: true
example: null
lastname:
type: string
nullable: true
example: null
email:
type: string
nullable: true
example: null
customer:
$ref: '#/components/schemas/PublicUserResponseCustomerDTO'
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prewave/refs/heads/main/openapi/prewave-users-api-openapi.yml