Authentication

Below endpoints allow you to obtain the access token required for accessing protected resources in the API. To obtain the access token, you need to make a request to the '/api/access-token' endpoint with the necessary credentials. Once you have obtained the token, it needs to be included as a header in all subsequent requests to protected endpoints. The 'Authorization' header should be set as 'Bearer [access_token]' for authentication.

This section of the documentation covers the process for obtaining two types of access tokens: the management token and the business token. Both tokens are acquired through the '/api/access-token' endpoint, but they serve different purposes and scopes.

Get Management access token

curl --request POST \
  "https://payments.your-domain.com/api/access-token" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"client_id\": \"your-client-id\",
    \"client_secret\": \"your-client-secret\",
    \"type\": \"management\",
    \"scope\": \"*\"
  }"

{
  "token_type": "Bearer",
  "type": "management",
  "expires_in": 31536000,
  "access_token": "your-bearer-token"
}

Get Business access token

curl --request POST \
  "https://payments.your-domain.com/api/access-token" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"client_id\": \"your-client-id\",
    \"client_secret\": \"your-client-secret\",
    \"business_id\": \"your-business-id\",
    \"type\": \"business\"
    \"scope\": \"*\"
  }"

{
  "token_type": "Bearer",
  "type": "business",
  "expires_in": 31536000,
  "access_token": "your-bearer-token"
}

Example Request using the bearer token returned from the above request.

Here's how to add the token to the request header using cURL:

curl https://payments.your-domain.com/v1/businesses \
  -H "Authorization: Bearer {token}"

Management Token vs Business Token

Understand the difference between the two types of access tokens.

Management Token

• Purpose: Grants access to all businesses and their respective data across the platform. Mainly used for backend integration and administrative purposes (e.g. creating new businesses, etc.).
• Scope: Wide-ranging, ideal for administrative or supervisory roles that require access to multiple businesses.
• Generation: Follow the standard token generation process without specifying a business ID.

Business Token

• Purpose: Restricts access to data pertaining to a single specified business. Mainly used for frontend sdk integration.
• Scope: Limited to one business, ensuring data isolation and security.
• Generation: Requires the inclusion of a business_id parameter in the token generation request.

Scopes

Scopes define the level of access a token will have to resources in Crater.