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.

​
Client credentials grant

Because our REST APIs are meant to be consumed by businesses, we only 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!

​
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.

​
On behalf of

Most of our API endpoints must be contextualized with a user, like creating a transaction or listing accounts.

Tokens issued using the client credentials grant type are meant to refer to the clients themselves. However, you can act on behalf of a user by adding the X-On-Behalf-Of: user {userId} HTTP header to the request, where {userId} is the ID of the user you want to target.

To use the X-On-Behalf-Of header to act on behalf of a user, the client must have the core.users:act-on-behalf-of scope.

​
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"]
}