Prewave Users - Roles API
🆕 NEW - API to manage user roles in the public network. Available from February 2026.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/prewave-users-roles-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Public Prewave Users - Roles API
description: Documentation of the Public Prewave API.
version: '1.0'
servers:
- url: https://api.prewave.com
description: Production Environment
security:
- Token authentication: []
tags:
- name: Users - Roles
description: 🆕 NEW - API to manage user roles in the public network. Available from February 2026.
paths:
/public/v1/users/{userId}/roles:
get:
tags:
- Users - Roles
summary: Retrieve roles assigned to a specific user
description: '### Overview
Retrieve all roles currently assigned to a specific user.
### Use Cases
- **Security Audits**: Verify that users only have the permissions necessary for their current function.
- **Troubleshooting**: Check if a user''s lack of access to a feature is due to missing roles.
### Identification
The `{userId}` is a unique numerical identifier.
### Getting User ID
- To find users and their numerical IDs, use the Users Management API:
- `GET /public/v1/users` - Retrieve all users with their `id` field.
- The `id` field in the user response is the `{userId}` used in this endpoint''s path parameter.
### Related Operations
- **Discover Valid Roles**: GET /public/v1/users/roles/available
- **Add Roles to User**: POST /public/v1/users/{userId}/roles
- **Remove Specific Role**: DELETE /public/v1/users/{userId}/roles/{roleName}
### Required Permission
`access_public_users`'
operationId: read
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 roles retrieved successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicUserRoleDTO'
examples:
Assigned Roles:
description: Assigned Roles
value: '[{"id":1,"name":"GRANT_USER_MANAGER_ACCESS","description":"User management role"},{"id":2,"name":"GRANT_TEAM_MANAGER_ACCESS","description":"Team management role"}]'
'404':
description: Not Found - The specified user does not exist.
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 }"
post:
tags:
- Users - Roles
summary: Assign new roles to a user
description: '### Overview
Assign one or more roles to an existing user.
### Use Cases
- **Privilege Escalation**: Grant a user additional management permissions.
- **Onboarding**: Finalize a user''s access setup by adding specific functional roles.
### Identification
The `{userId}` is a unique numerical identifier.
### Getting User ID
- To find users and their numerical IDs, use the Users Management API:
- `GET /public/v1/users` - Retrieve all users with their `id` field.
- The `id` field in the user response is the `{userId}` used in this endpoint''s path parameter.
### Behavior
- **Additive**: This operation only adds new roles. It will **not** remove or overwrite existing roles.
- **Validation**: Every role name provided must be valid and assigned to your organization. If even one role name is invalid, the entire request will fail (atomic operation).
### Workflow Tip
Call List Available Roles first to ensure you are using correct role names.
### Related Operations
- **List Current Roles**: GET /public/v1/users/{userId}/roles
- **Remove Role**: DELETE /public/v1/users/{userId}/roles/{roleName}
### Required Permission
`manage_public_users`'
operationId: add
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: List of role identifiers to assign.
content:
application/json:
schema:
type: array
items:
type: string
examples:
Batch Role Assignment:
summary: Adding multiple roles in a single request
description: Batch Role Assignment
value: '["GRANT_USER_MANAGER_ACCESS","GRANT_TEAM_MANAGER_ACCESS"]'
required: true
responses:
'201':
description: Created - Roles successfully added. Returns the full, updated list of user roles.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicUserRoleDTO'
examples:
Updated Role List:
description: Updated Role List
value: '[{"id":1,"name":"GRANT_USER_MANAGER_ACCESS","description":"User management role"},{"id":2,"name":"GRANT_TEAM_MANAGER_ACCESS","description":"Team management role"},{"id":3,"name":"GRANT_ACTIONS_ACCESS","description":"Action management role"}]'
'404':
description: Not Found - Either the user ID is invalid or one of the role names provided does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Role Not Found:
summary: Occurs when a role name is misspelled or invalid
description: Role Not Found
value: '{"code":"role_not_found","message":"Role ''UNKNOWN_ROLE'' does not exist."}'
'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/roles/available:
get:
tags:
- Users - Roles
summary: List all available role definitions
description: '### Overview
Retrieve a list of all role names that can be assigned to users within your organization.
### Use Cases
- **Discovery**: Find out which roles are valid for assignment before calling the Add Roles endpoint.
- **UI Population**: Populate a dropdown in your internal management tool with valid role names and descriptions.
### Why Use This?
Use this endpoint to discover valid role identifiers before assigning them. This ensures you only use roles that are active and compatible with your organization''s permissions.
### Related Operations
- **Assign Roles to User**: POST /public/v1/users/{userId}/roles
- **View User''s Roles**: GET /public/v1/users/{userId}/roles
- **Onboard New User**: POST /public/v1/users
### Required Permission
`access_public_users`'
operationId: getAvailableRoles
responses:
'200':
description: Available roles retrieved successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicUserRoleDTO'
examples:
Assignable Roles List:
summary: Full list of roles available for assignment
description: Assignable Roles List
value: '[{"id":1,"name":"GRANT_USER_MANAGER_ACCESS","description":"Full access to user management features."},{"id":2,"name":"GRANT_TEAM_MANAGER_ACCESS","description":"Ability to create and manage teams."},{"id":3,"name":"GRANT_ACTIONS_ACCESS","description":"Permission to handle action items and alerts."}]'
'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 }"
/public/v1/users/{userId}/roles/{roleName}:
delete:
tags:
- Users - Roles
summary: Revoke a specific role from a user
description: '### Overview
Revoke a specific role from an existing user.
### Use Cases
- **Access Reduction**: Downgrade a user''s permissions when they move to a different team or department.
- **Security**: Remove access that is no longer required as part of the principle of least privilege.
### Identification
- **userId**: Numerical identifier of the user.
- **roleName**: The exact string identifier of the role (e.g., `ROLE_USER_MANAGER`).
### Getting User ID
- To find users and their numerical IDs, use the Users Management API:
- `GET /public/v1/users` - Retrieve all users with their `id` field.
- The `id` field in the user response is the `{userId}` used in this endpoint''s path parameter.
### Getting Role Names
- Discover valid role names via `GET /public/v1/users/roles/available`.
### Related Operations
- **Add Roles**: POST /public/v1/users/{userId}/roles
- **List All Roles**: GET /public/v1/users/{userId}/roles
### Required Permission
`manage_public_users`'
operationId: delete
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
- name: roleName
in: path
description: The exact internal name of the role to remove. Discover valid names via the [Available Roles](#operations-Users_-_Roles-getAvailableRoles) endpoint.
required: true
schema:
type: string
example: ROLE_USER_MANAGER
responses:
'204':
description: No Content - Role successfully removed.
'404':
description: Not Found - User or Role identifier not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorDTO'
examples:
Role Not Found:
description: Role Not Found
value: '{"code":"role_not_found","message":"The user does not possess the role ''ROLE_USER_MANAGER''."}'
'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:
ApiRateLimitResponse:
type: object
properties:
error:
type: string
description: Error type identifier
example: RateLimitExceeded
message:
type: string
description: Human-readable error message explaining the rate limit violation
example: API rate limit exceeded. Please reduce your request rate.
requestLimit:
type: integer
description: Maximum number of requests allowed in the current time window
format: int32
example: 100
requestCount:
type: integer
description: Number of requests made in the current time window
format: int32
example: 101
limits:
type: array
description: All rate limits that apply to this endpoint, showing different time windows
items:
$ref: '#/components/schemas/ApiRateLimitTimeRequestLimit'
example: null
currentTime:
type: string
description: Current server time in ISO 8601 format
format: date-time
example: '2026-01-19T10:30:00'
nextResetAt:
type: string
description: Time when the rate limit will reset in ISO 8601 format
format: date-time
example: '2026-01-19T10:30:10'
description: Response returned when API rate limit is exceeded (HTTP 429)
example: null
PublicUserRoleDTO:
required:
- id
- name
type: object
properties:
id:
type: integer
format: int32
example: null
name:
type: string
example: null
description:
type:
- string
- 'null'
example: null
example: null
ApiRateLimitTimeRequestLimit:
type: object
properties:
requestLimit:
type: integer
description: Maximum number of requests allowed in this time window
format: int32
example: 100
timeInSeconds:
type: integer
description: Time window duration in seconds
format: int32
example: 10
description: Rate limit configuration for a specific time window
example: null
AccessDeniedErrorDTO:
required:
- code
- loggedIn
- message
type: object
properties:
loggedIn:
type: boolean
example: null
permission:
type:
- string
- 'null'
example: null
code:
type: string
description: Error code
example: null
message:
type: string
description: Error message
example: null
solution:
type:
- string
- 'null'
description: Possible solution to the error
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
- 'null'
description: Possible solution to the error
example: null
description: Error response
example: null
securitySchemes:
Token_authentication:
type: apiKey
description: Generate an API token at https://www.prewave.com/management/api and paste it in here.
name: X-Auth-Token
in: header