Token Scopes

Overview

The Cybrid Platform API uses OAuth 2.0 Bearer Tokens to authenticate requests. You retrieve bearer tokens using your client_id and client_secret credentials, which you generate through the Cybrid Partner Portal.

Three types of bearer tokens exist:

• Organization tokens — apply to the entire Organization and all its Banks.
• Bank tokens — scoped to an individual Bank.
• Customer tokens — scoped to a specific customer within a Bank.

Both Organization and Bank tokens use the OAuth Client Credential Grant flow. Each Organization and Bank has a unique Client ID and Secret for machine-to-machine authentication.

Authentication scopes

When generating a bearer token, you must specify authentication scopes. Scopes fall into three categories:

• Read — list and retrieve resources on the platform
• Write — update resources on the platform
• Execution — create resources on the platform

Use the scope with the least privileges necessary. For example, rather than using an Organization token to list a customer's trades, generate a Customer token with the trades:read scope.

For more information, 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 Platform Overview for details on how these resources interact.

Generate a token

Use a tool like httpie to generate a token from the 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>"

Token caching and rate limiting

Cache the generated access token based on the expires_in attribute in the token response. Tokens can typically be cached for up to 30 minutes. Only generate a new token when the current one nears expiration.

⚠️

Rate limiting

Cybrid enforces rate limiting on POST /oauth/token and POST /oauth/customer_token. If you exceed the rate limit, the API returns 403 (Forbidden). Cache tokens to avoid hitting this limit.