Skip to content

User Management API for Resellers#

Although we highly recommend using the builtin user-management interface on platform.natif.ai, we also provide programmatic access to user-management features via REST API. The following section summarizes key terms and concepts behind our user management beyond the auto-generated API specification.

Important

This feature is targeted at our customers that are also Resellers. If you don't know what this means, or you don't know whether this applies to you, then it probably doesn't apply to you and you can ignore this entire section 😉

Realms vs. Customers vs. Users#

Users of natif.ai services (i.e. user-accounts that human users can authenticate for via email and password) are partitioned in the following ways:

Hint

In a sense, User accounts in many ways act as representatives of the Customer entity they are a part of.

Each User belongs to a Customer, as such Customers essentially represent Groups of Users that share certain resources, e.g.

  • Stored Documents
  • Annotation Projects
  • Custom Workflows
  • Pricing Model, Limits and Quotas

Each Customer belongs to exactly one Realm. Realms are basically overarching, isolated environments for Customers and Users. As a Reseller, you are eligible to manage all Customers and their Users within the borders of your own dedicated Realm, as well as inspect their meta-data, configurations and processing usage tracking.

User Roles#

User accounts within a customer can have one of the following Roles, which determines the actions they can perform on platform.natif.ai and via the API.

Role Manager User / "Clerk"
Identifier manager user
User management ✅
(Managers and Users)
-
Upload for Processing ✅ ✅
Result Retrieval ✅ ✅
Insights ✅
Processing usage & quotas
✅
Basic processing usage

When user lists are retrieved via API, additional roles may appear, these are of technical nature and are typically not relevant to human user accounts.

Create#

Customers can be created via the POST /reseller/customers endpoint. See also the auto-generated API documentation.

Request Body#

FieldTypeDescription
name string Should be a unique and speakable name to later on reliably identify the customer.
organizational_info object Holds meta-data about the organization related to this customer, e.g. addresses or additional data-protection flags. For the exact shape of this object, please refer to the Schema definition in the auto-generated API specification.
use_technical_interface bool If set to `true`, all Users within this Customer will be presented the extended technical interface after login on platform.natif.ai. This is recommended only if Users from this customer will need features that the new Interface does not (yet) provide. By default (recommended), they will be shown the new streamlined web experience. Can be changed afterwards.

Response#

On success, returns a JSON object containing the single key customer_id, defining the unique identifier for the newly created customer. This identifier is needed for any other related action for this customer, e.g. managing users within it, modifying settings, retrieving usage metrics, etc.

Modify#

Customers with a known customer_id can be modified via the PUT /reseller/customers/{customer_id} endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer.

Request Body#

The submitted application/json body parameters are similar to the ones provided at time of initial customer creation. Values that are not included into the submitted JSON body will not be updated and stay as-is, i.e. the data update can be partial.

Response#

On success, returns an empty response.

Delete#

Customers with a known customer_id can be deleted via the DELETE /reseller/customers/{customer_id} endpoint. See also the auto-generated API documentation.

Warning

Deleting the customer also deletes all remaining user accounts within this customer! Please be careful!

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer.

Response#

On success, returns an empty response.

List#

With the GET /reseller/customers endpoint, you can list all existing customers from your own realm. See also the auto-generated API documentation.

Response#

On success, returns an application/json response body containing a list of User objects in the following form:

Customer object
{
  "name": "string",
  "organizational_info": {
    "company_name": "string",
    "industry": "string",
    "number_of_employees": 0,
    "sector": "string",
    "paragraph_203_StGB_applies": true,
    "address": {
      "address_line_1": "",
      "address_line_2": "",
      "city": "string",
      "zip_code": 0,
      "country": "AD"
    },
    "additional_sensitive_personal_data_attributes": "string"
  },
  "use_technical_interface": true
}

Create#

User accounts can be created via the POST /reseller/customers/{customer_id}/users endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer this user should be created in.

Request Body#

The request to this endpoint needs to include an application/json encoded object containing the following fields:

FieldTypeDescription
username string >email< The email for the new user. If no initial password is provided, instructions on how to complete the account setup are sent to this address.
password (optional) string The default is to not provide a password. In this case the customer is sent an email with a link to verify the email address and set the password. If a password is provided, it is assumed that the email is verified and no further communication is sent to the customer. The password must be at least 12 characters long and must contain:
  • a minimum of 1 lower case letter [a-z] and
  • a minimum of 1 upper case letter [A-Z] and
  • a minimum of 1 numeric character [0-9] and
  • a minimum of 1 special character:
    ~!@#$%^&*()-_+={}[]|;:<>,./?
role One of "manager" | "user" The role that will be assigned to this user and dictate the overall permissions the user will have within its customer.
first_name (optional) string The first name of the user.
last_name (optional) string The last name of the user.
job_title (optional) string The job title of the user

Response#

On success, returns a JSON object containing the single key user_id, defining the unique identifier for the newly created user. This identifier is needed for any other related action for this user, e.g. updating or deleting it, etc.

Update#

User accounts can be modified via the PUT /reseller/customers/{customer_id}/users/{user_id} endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer this user is located in.
{user_id} UUID The identifier for the user that is to be modified.

Request Body#

The request to this endpoint needs to include an application/json encoded object containing the following fields:

FieldTypeDescription
first_name (optional) string The first name of the user.
last_name (optional) string The last name of the user.
job_title (optional) string The job title of the user

Fields that are not provided as part of the body or sent with a null value will not be updated and remain unmodified.

Response#

On success, returns an empty HTTP Response

Delete#

User accounts can be deleted via the DELETE /reseller/customers/{customer_id}/users/{user_id} endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer this user should be deleted from.
{user_id} UUID The identifier for the user that is to be deleted.

Request Body#

None

Response#

On success, returns an empty HTTP Response

List#

User accounts within a customer can be listed with the GET /reseller/customers/{customer_id}/users endpoint. See also the auto-generated API documentation.

Parameters#

FieldTypeDescription
{customer_id} UUID The identifier for the customer whose users should be returned.

Request Body#

None

Response#

On success, returns an application/json response body containing a list of User objects in the following form:

User object
  {
    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
    "username": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "job_title": "Engineer",
    "role": "user"
  }