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.
Customer-related Endpoints#
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
}
User-related Endpoints#
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:
|
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: