User Management API
Allows you to query, invite, deactivate and reactivate users. It can be used in combination with access grants to restrict users access to certain customers or on it's own.
The User Object
The user object is returned by all endpoints that retrieve user information. It has the following fields:
Field | Type | Description |
---|---|---|
id | UUID | The unique identifier for the user. |
email | string | The user's email address. |
name | string | The user's full name. This may be empty if the user has not registered yet. |
role | string | The user's role in the organisation. e.g. basic_user . |
type | string | The type of user. For user management, this is always USER . Feel free to ignore this field. |
is_active | boolean | Whether the user is active and can log in. |
registration_confirmed | boolean | Whether the user has completed the registration process. |
registration_invite_expired | boolean | Whether the user's registration invite has expired. |
List Users: GET /api/v2/users
GET /api/v2/users
This endpoint retrieves a list of users for the organisation.
Query Parameters
is_active
(boolean, optional): Filter by active status. Example:true
orfalse
. By default, all users are returned.email
(string, optional): Filter by email address.role
(string, optional): Filter by user role. E.g.basic_user
,user
,advanced_user
,admin
.
Request
curl -X GET "https://api.inscribe.ai/api/v2/users/?is_active=true" \
-H "Authorization: Inscribe <YOUR_API_KEY>"
Response
A successful response returns a JSON object with a data
key containing a list of user objects.
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "[email protected]",
"name": "Test User",
"role": "basic_user",
"type": "USER",
"is_active": true,
"registration_confirmed": true,
"registration_invite_expired": false
}
]
}
Get a single user: GET /api/v2/users/:user_uuid
GET /api/v2/users/:user_uuid
This endpoint retrieves a single user by their UUID.
Path Parameters
user_uuid
(string, required): The UUID of the user.
Request
curl -X GET "https://api.inscribe.ai/api/v2/users/123e4567-e89b-12d3-a456-426614174000/" \
-H "Authorization: Inscribe <YOUR_API_KEY>"
Response
A successful response returns a single user object.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "[email protected]",
"name": "Test User",
"role": "basic_user",
"type": "USER",
"is_active": true,
"registration_confirmed": true,
"registration_invite_expired": false
}
Invite a User: POST /api/v2/users/invite
POST /api/v2/users/invite
This endpoint invites a new user to the organisation.
This works in the same way as via the UI: The user gets access to the workspace and in case the user doesn't exist yet, a new user is created and receives an email for the registration process.
Currently, only users with the basic_user
role can be invited.
Request Body
email
(string, required): The email address of the user to invite.role
(string, required): The role to assign to the user. Must bebasic_user
.
Request
curl -X POST "https://api.inscribe.ai/api/v2/users/invite/" \
-H "Authorization: Inscribe <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"role": "basic_user"
}'
Response
A successful response returns the invited user object.
{
"id": "223e4567-e89b-12d3-a456-426614174001",
"email": "[email protected]",
"name": "",
"role": "basic_user",
"type": "USER",
"is_active": true,
"registration_confirmed": false,
"registration_invite_expired": false
}
Deactivate a user: POST /api/v2/users/:user_uuid/deactivate
POST /api/v2/users/:user_uuid/deactivate
This endpoint deactivates a user, preventing them from logging in. If the user is not registered and has a pending invite, the invite is canceled.
Currently, only users with the basic_user
role can be targeted.
Path Parameters
user_uuid
(string, required): The UUID of the user.
Request
curl -X POST "https://api.inscribe.ai/api/v2/users/123e4567-e89b-12d3-a456-426614174000/deactivate/" \
-H "Authorization: Inscribe <YOUR_API_KEY>"
Response
A successful response returns the updated user object.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "[email protected]",
"name": "Test User",
"role": "basic_user",
"type": "USER",
"is_active": false,
"registration_confirmed": true,
"registration_invite_expired": true
}
Reactivate a user: POST /api/v2/users/:user_uuid/reactivate
POST /api/v2/users/:user_uuid/reactivate
This endpoint (re-)activates a user, allowing them to log in again. The user must have already registered. If the user is already active, nothing happens.
Currently, only users with the basic_user
role can be targeted.
Path Parameters
user_uuid
(string, required): The UUID of the user.
Request
curl -X POST "https://api.inscribe.ai/api/v2/users/123e4567-e89b-12d3-a456-426614174000/reactivate/" \
-H "Authorization: Inscribe <YOUR_API_KEY>"
Response
A successful response returns the updated user object.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "[email protected]",
"name": "Test User",
"role": "basic_user",
"type": "USER",
"is_active": true,
"registration_confirmed": true,
"registration_invite_expired": true
}
FAQs
Which roles can API-managed users have?
Currently, only users of type basic_user
can be created / changed via the API. However, this can easily be extended to other roles upon request.
Updated about 20 hours ago