Skip to main content
All requests must be authenticated or they will be rejected with a 401 Unauthorized status code.

​
OAuth2

Our REST APIs use the industry standard OAuth2 protocol for authentication. It’s a well defined and widely used specification for token-based authentication and authorization.

​
Grant types

Because our REST APIs are meant to be consumed by businesses, we support the client credentials grant type. For this grant, you need to provide a valid client ID and client secret to create access tokens. To obtain an access token, you may call the Request OAuth2 Token endpoint. You can then use access tokens to authenticate subsequent requests by adding the Authorization: Bearer {accessToken} HTTP header.
You can manage your clients in Enterprise Portal. Please note that client secrets act like passwords, so be sure to keep them secure!

​
Subjects

Calls to our REST API endpoints are always contextualized with a subject. A subject represents the actor performing the action, which can be one of the following:
  • client: The OAuth2 client itself, used for operations that don’t require user context
  • user:individual: An individual user within an organization
  • user:business: A business user within within an organization
Depending on your client configuration, the client’s tokens may be able to target different subjects:
  • Organization-wide clients default to the client subject but can act on behalf of any user within an organization, provided they have the core.users:act-on-behalf-of scope. Add the X-On-Behalf-Of: user {userId} HTTP header to the request, where {userId} is the ID of the user you want to target.
  • Single-user clients are associated with a specific user within the organization and can only perform actions on behalf of that user. No additional header is required.

​
Scopes

Clients are associated with a set of scopes that define the permissions of tokens. This allows you to create as many clients as needed, each with a different set of permissions based on your requirements. If you attempt to call an endpoint that requires certain scopes, but the token you are using doesn’t have them, you will receive a 403 Forbidden status code.

​
API keys

API keys are another widely used way to authenticate requests, but we have chosen not to support them for now. If you have a use case that requires API keys, please reach out to us, and we will consider adding support for them.

​
User blocked

If a user is internally blocked, every request to non GET endpoints will fail with 409 HTTP status code and the following body: 
{
  "code": "operation-not-allowed",
  "message": "The current status of the user does not allow calling this endpoint",
  "reasons": ["user-blocked"]
}