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.

ℹ️

Organization-level scopes

Some scopes, such as banks:execute, require Organization-level credentials (Organization API keys) and cannot be
used with Bank-level credentials. Attempting to use these scopes with Bank-level credentials will result in an
invalid_scope error. Use your Organization API keys when creating new banks or performing
organization-level operations.

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.