Client Credentials

The Client Credentials flow is used for server-to-server authentication. Use this flow when your application needs to access API resources on behalf of itself (not a specific user or on behalf of a merchant).

Specification: RFC 6749 Section 4.4

Prerequisites

Before you can authenticate with the API Gateway, you need to have an application set up to retrieve the following data:

Client ID: A unique identifier for your application
Client Secret: A secret key for authentication (provided when your application is created)

These credentials are obtained when you register an application in the My Buckaroo portal. The Client Secret will only be returned once so make sure to store this in a secure and reliable place. There is no limit the the number of applications that can be created. Each application can have their own set of scopes to allow using an application per use-case.

Access Token Retrieval

Request Format

Endpoint: POST /oauth/token

Headers:

Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/x-www-form-urlencoded

Body Parameters:

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be `client_credentials`
`scope`	string	No	Space-separated list of scopes in `audience:operation` format. If omitted, all of the application's scopes are included.

Successful Response

HTTP Status: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response Fields:

Field	Type	Description
`access_token`	string	The JWT access token to use for API authentication
`token_type`	string	The token type (always `Bearer`)
`expires_in`	number	Token validity period in seconds