Request Authentication#
Unless stated otherwise and tagged anonymous, all requests require the user to be authenticated.Additionally, all requests require the user to be logged in to a tenant corp, unless tagged no-tenant, which means that the request affects the user, not their current tenant.Authentication Types#
Bearer token by service password#
This is the legacy authorisation method for service accounts still using a password (might be referred to as "API key").
You can check this by looking at the service in your Users list ; if you don't see an "API Keys" section, you are still using a password. GET auth/login request including a Authorization: Plaintext (login_id) (api_key) header, with a bearer token value provided on success.All subsequent requests must provide the supplied bearer token in each request, using the Authorization: Bearer ... header.Bearer token by service API key#
This is only available if your service account profile has the "API Keys" section.
GET auth/login request including a Authorization: API_HMAC ... header, with a bearer token value provided on success.The value of the header is an HMAC SHA256 hash of the username and current UNIX timestamp. The timestamp must be within 30 seconds of either side of the current server time (synchronised UTC).All subsequent requests must provide the supplied bearer token in each request, using the Authorization: Bearer ... header.Two-Factor Authentication Checks#
Service accounts currently do not support two-factor authentication and requests requiring such will fail.There is a roadmap proposal for this feature, but it currently has no timeframe.
Request Authorisation#
If specific tenant permissions are required to invoke a request, they will be detailed in the request description, including any permissions specific to accessing the entity.Modifying a user's roles requires the user / modify permission, but you must already have the user / view permission to be able to see that the user is a member of the tenant.
403 Forbidden response will include a Warning: 199 - Permissions header.
The exact permissions required are not exposed on the request.Role-based access management#
User authorisation is handled per tenant using "security roles", where these are a set of permissions that can be "granted" or "denied".A user's final set of abilities (the set of permissions that apply to them for the current tenant) is the intersection of all granted permissions without any of the denied ones, plus any internal abilities provided based on other factors.| | user / view | user / modify | user / delete |
|---|
| Role 1 | Grant | Deny | Unset |
| Role 2 | Unset | Grant | Grant |
| Applied to user | Applied | Denied | Applied |
user / view in the self context will grant/deny the user to see their own user profile. The others context applies to all non-self entities.