Authentication

Banked uses the OAuth2 authentication framework to authenticate requests to our APIs from Partner accounts.

Use the /token endpoint of the Partner API to generate OAuth tokens.

Tokens expire after 2 hours, so you must rotate your tokens frequently to ensure application security.

Banked OAuth tokens can be scoped or unscoped:

• Scoped - To authenticate requests to any of the Banked Payments API resources you must use a token that is scoped to a specific business application. To create a scoped token, send a POST request to the /token endpoint with an application ID in a --data-urlencode header. Application IDs are obtained using a request to the /business_applications endpoint.
• Unscoped - Use an unscoped token to authenticate requests to any of the Partner API endpoints to perform actions like boarding new merchants and getting application IDs.

This page describes how to generate and use OAuth tokens.

Generating an OAuth tokenCopy URL

Once you are onboarded as a Banked Partner, you will be issued an API key and secret by our onboarding team.

To generate OAuth tokens, create an Authorization header by concatenating your API key and secret key with a colon as a separator, and then base64 encode the resulting string: Authorization: Basic base64(APIkey:secretKey).

The example below shows a scoped token request with the application ID in the data-urlencode field:

curl --location --request POST 'https://api.banked.com/oauth/token' \
--header 'Authorization: Basic base64(key:secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=APPLICATION_ID'

The example below shows the format of the token response:

{
  "access_token": "YOUR_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "APPLICATION_ID",
  "created_at": 1615831274
}

You can now use the OAuth token from the access_token field to authenticate your API requests. To authenticate your requests, include an authorization header as shown below:

Authorization: Bearer YOUR_TOKEN