Guides

Authenticate to the API

Learn about client_id/client_secret, generated bearer tokens, and authorization scopes.

The Cybrid Platform API leverages a few different mechanisms in order to securely authorize calls against the system. We'll explain all of those below.

General Overview

The Cybrid Platform uses OAuth 2.0 Bearer Tokens to authenticate requests to the platform. Bearer tokens can be retrieved from the platform client_id and client_secret credentials. These credentials, can be generated via the Cybrid Partner Portal.

There are several types of bearer tokens that can be created: Organization tokens, Bank tokens, and Customer tokens.

An Organization access token applies broadly to the whole Organization and all of its Banks, whereas, a Bank access token is specific to an individual Bank. Customer tokens, similarly, are scoped to a specific customer in a bank.

Both Organization and Bank tokens can be created using the OAuth Client Credential Grant flow. Each Organization and Bank has its own unique Client ID and Secret that allows for machine-to-machine authentication.

Authentication Scopes

When generating a bearer token with a provided client_id and client_secret, the authentication scopes must be specified. The scopes are categorized into three different types:

  • Read scope: used to read and list resources on the platform
  • Write scope: used to update resources on the platform
  • Execution scope: used to create resources on the platform

When designing your authentication regime, we recommend using the scope with the least privileges necessary to take a specific action. For example, while it's entirely possible to use an Organization token to request a list of historical trades for a customer, it's overkill to do so, as the organization token could have full authority to make sweeping platform changes. The better solution is to generate a Customer token for the specific customer, with the trades:read scope, to request a list of historical trades.

For more information on security best practices see How do I securely Implement Cybrid?

Scopes apply to the following resource types:

  • Account
  • Bank
  • Customer
  • Deposit Address
  • External Bank Account
  • Organization
  • Price
  • Quote
  • Trade
  • Transfer
  • Workflow

See the How is the Platform Structured for more information on how the resources interact.

Generating a Token

Use something like httpie at the command line, while supplying your credentials, to generate a token.

Example command line:

http -v post https://id.sandbox.cybrid.app/oauth/token \
    grant_type=client_credentials \
    client_id=<YOUR_BANK_CLIENT_ID> \
    client_secret=<YOUR_BANK_CLIENT_SECRET> \
    scope="<YOUR_SCOPES_HERE>"

Access Token Caching and Rate Limiting

To optimize performance and reduce unnecessary API requests, you should cache the generated access token based on the expires_in attribute provided in the token response. Typically, tokens can be cached for up to 30 minutes, depending on the expires_in value. Ensure that your application respects this caching duration and only generates a new token when the current one is near expiration.

Rate Limiting (Effective October 1st, 2024)

Starting October 1st, 2024, Cybrid will implement rate limiting on access token generation. To avoid exceeding rate limits, it's essential to cache the token as described above and refrain from making unnecessary requests. This new rate limit will restrict how frequently new tokens can be generated, so proper caching will help maintain your application's smooth operation.

If you have reached the /oauth/token or /oauth/customer_token endpoint rate limits the API will return 403 (Forbidden)

Updated 2 months ago