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:

FieldTypeDescription
idUUIDThe unique identifier for the user.
emailstringThe user's email address.
namestringThe user's full name. This may be empty if the user has not registered yet.
rolestringThe user's role in the organisation. e.g. basic_user.
typestringThe type of user. For user management, this is always USER. Feel free to ignore this field.
is_activebooleanWhether the user is active and can log in.
registration_confirmedbooleanWhether the user has completed the registration process.
registration_invite_expiredbooleanWhether the user's registration invite has expired.

List 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 or 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

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

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 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

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

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.