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#

Field	Type	Description
`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#

Field	Type	Description
`{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#

Field	Type	Description
`{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#

Field	Type	Description
`{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:

Field	Type	Description
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#

Field	Type	Description
`{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:

Field	Type	Description
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#

Field	Type	Description
`{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#

Field	Type	Description
`{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"
  }

User Management API for Resellers#

Realms vs. Customers vs. Users#

User Roles#

Customer-related Endpoints#

Create#

Request Body#

Response#

Modify#

Parameters#

Request Body#

Response#

Delete#

Parameters#

Response#

List#

Response#

User-related Endpoints#

Create#

Parameters#

Request Body#

Response#

Update#

Parameters#

Request Body#

Response#

Delete#

Parameters#

Request Body#

Response#

List#

Parameters#

Request Body#

Response#