Authentication

Steps for Accessing the Crater API

  1. Create an API Client: Obtain the client ID and secret from the Developers -> API Clients page.

  2. Setup User and Roles: Configure roles appropriately before creating a user.

  3. Generate Access Token:

    • Use the below given endpoint to generate an access token.
    • Utilize this access token in subsequent API requests.
POSToauth/token

Generate Access Token

You will need a user ID for which you want to generate the token. Please read the Quickstart guide for more information.

Send these values as params in the POST body and get the access token.

Parameters

  • Name
    grant_type
    Type
    string
    Field Type
    Description

    Pass personal_access as the grant type.

  • Name
    client_id
    Type
    string
    Field Type
    Description

    Pass your client id given by Crater

  • Name
    client_secret
    Type
    string
    Field Type
    Description

    Pass your client secret given by Crater

  • Name
    user_id
    Type
    string
    Field Type
    Description

    Pass user_id of the user for which you want to get the access token.

Keep your access token safe! Also be mindful about the ID of the user you are generating the token for. You can read about token types in the Token Types section.

Request

POST
oauth/token
curl --request POST \
  "https://payments.your-domain.com/oauth/token" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"grant_type\": \"personal_access\",
    \"client_id\": \"your-client-id\",
    \"client_secret\": \"your-client-secret\",
    \"user_id\": \"your-crater-user-id\"
  }"

Response

{
  "token_type": "Bearer",
  "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:

Example request with bearer token

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

Token Types :

There are 2 types of tokens in Crater API:

  • Platform Access Token: Used to manage businesses, users, and other resources across the platform. For example the super admin user of the platform.
  • Business Access Token: Used to manage resources within a specific business. For example the business owner or accountant. of a specific business.

The token type is determined by the user_id you pass in the request. If you pass the user_id of a super admin user, you will get a platform access token. If you pass the user_id of a business owner or accountant, you will get a business access token.