How to 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
• Reward
• Trade
• Transfer
• Workflow

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

Generating a Token

For testing purposes, there's two easy methods to generate a token:

UI Approach:

Use our interactive swagger docs to Authorize with your client_id and client_secret. Find the Authorize button, and enter your credentials:

Command Line Approach

Use something like httpie at the command line, while supplying your credentials, to generate the 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>"