Skip to main content


๐Ÿ“„๏ธ Mint a token for a person

This endpoint creates a token for a specific user. Custom claims can be specified in the request body which will be added to the token's payload. Custom claims are added to the token's payload. Tokens created with this endpoint will have an `authenticated_methods` claim equal to ['api']. The following claims are reserved and cannot be specified: - aud - exp - jti - iat - iss - nbf - sub - prev_token_id - oid - org_id - user_id - person_id - first_token - authenticated_methods - oidc_tokens - user_token - groups - roles - access_token - refresh_token - id - id_token - gdpr - gdpr_consent - gdpr_consent_level - parent_user_id - parent_person_id - parent_org_id - parent_oid - attributes - custom_claims - slashid - - - - sid With the following request body: ``` { 'custom_claims': { 'foo': 'bar', 'baz': {'everything': 42} } } ``` the token in the response will have the following payload: ``` { 'authenticated_methods': [ 'api' ], 'baz': { 'everything': 42 }, 'exp': <expiration time timestamp>, 'first_token': false, 'foo': 'bar', 'iat': <issued at timestamp>, 'iss': <token issuer>, 'jti': <token ID>, 'oid': <organisation ID>, 'person_id': <person ID> } ```

๐Ÿ“„๏ธ Set the groups for a person

Add the person to the groups specified in the request body, and remove the person from any other existing groups. All groups in the request body must already exist. Duplicate groups in the request body will be ignored. If an empty list is supplied in the request body, the person will be removed from all groups they are currently a member of, and will not be added to any others. New groups can be created with the [POST /groups](/docs/api/post-groups) endpoint.

๐Ÿ“„๏ธ Retrieve the list of person's organizations

Retrieve details of all the organizations a person belongs to, including: - The organization of the request: the person must be a member of the organization you authenticate with for you to be allowed to retrieve this list - Any sub- and super-organizations that share the person pool with the organization of the request: A hierarchy of organizations can be created using [this API endpoint](/docs/api/post-organizations-suborganizations). When organizations are configured to share a person pool, if the same person registers with multiple organizations in the pool using the same handle, all organizations will see the same person ID for that person.

๐Ÿ“„๏ธ Create new person

Create a new person linked to your organization. The request must contain at least one handle for the person (email address, phone number, or username). Optionally, you can specify a list of roles, a geographical region and attributes. Attributes are a map from attribute bucket names to key-value pairs. If a person with the specified handles already exists, an error will be returned. If the region is not specified, the person will be created in the region closest to the region of your backend. If you explicitly specify the region and a person with the provided handle already exists in a different region, this endpoint will return an error. A person's region association is eventually consistent between regions. Because of that, creating a person between regions within the time frame of data replication can result in a person being created in multiple regions. You can learn more on the [Cross-region replication model](/docs/access/concepts/replication) page.