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/usersThis endpoint retrieves a list of users for the organisation.
Query Parameters
- is_active(boolean, optional): Filter by active status. Example:- trueor- false. 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_uuidThis 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/inviteThis 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.
Request Body
- email(string, required): The email address of the user to invite.
- role(string, required): The role to assign to the user. Must be- basic_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/deactivateThis endpoint deactivates a user, preventing them from logging in. If the user is not registered and has a pending invite, the invite is canceled.
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/reactivateThis 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.
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 with the roles basic_user, advanced_user and advanced_readonly_user can be created / changed via the API. If you need to manage another role via the API, please just reach out.
Updated 15 days ago
