Guides
StatusPlazaCreate Account
Start typing to search…

Authentication/Security/Scope

Buckaroo APIs use OAuth 2.0 bearer tokens for authentication and authorization. An access token represents the permissions (scopes) that a client has been granted. Buckaroo supports two main OAuth scenarios:

  1. Single-tenant integrations – your own backend talks to your own Buckaroo account using client credentials.
  2. Multi-tenant integrations – a Third-Party App acts on behalf of multiple Buckaroo merchants, using user consent and refresh tokens (currently in beta).

1. Single-tenant QAuth (client credentials)

In the single-tenant scenario, your system uses a client ID and client secret to obtain an access token. This is typically used when you are only accessing resources from your own Buckaroo account.

Token endpoint

POST /oauth/token

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

&client_id={CLIENT_ID}

&client_secret={CLIENT_SECRET}

&scope={SPACE_SEPARATED_SCOPES}

Example response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
  • access_token – JWT bearer token you send to the Buckaroo API.
  • token_type – always Bearer.
  • expires_in – lifetime of the access token in seconds.

Calling the Buckaroo API

Include the access token in the Authorization header:

GET /resource

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

If the token is expired or does not have the required scopes, the API will return an error (typically 401 or 403).

Example response

{
    "Title": "Unauthorized",
    "Status": 401,
    "Detail": "An authentication error occurred: Invalid access token",
    "ErrorCode": null
}

2. QAuth scopes

Scopes define what your application is allowed to do.

When requesting a token, you pass a space-delimited list of scopes in the scope parameter.

scope=customer:read customer:save sale:read sale:save

Supported scopes

Adjust the descriptions to match your exact product language if needed.

Hosted Fields

  • scope:hostedfields:save – create or update Hosted Fields configurations.

API keys

  • apikey:read – read existing API keys and their metadata.
  • apikey:save – create or update API keys.

Point of sale (POS)

  • pos:terminals:read – read POS terminals, their capabilities and status.
  • pos:terminals:save – create or update POS terminals and their configuration.
  • pos:transactions:create – initiate POS payment transactions on a terminal.
  • pos:transactions:read – read details and status of POS transactions.
  • pos:transactions:refund – create refunds for completed POS transactions.
  • pos:reports:read – read POS turnover, settlement and reconciliation reports.

Subscriptions

  • subscriptions:save – create or update subscriptions.
  • subscriptions:deactivate – deactivate subscriptions.
  • subscriptions:read – read subscription details.
  • subscriptions:activate – activate paused/inactive subscriptions.
  • subscriptions:reprioritise – change processing priority/order of subscriptions.

Reports & report scheduling

  • report:save – create or update report definitions or report runs.
  • report:read – retrieve generated reports or report metadata.
  • reportdefinition:read – read available report definitions.
  • reportschedule:save – create or update report schedules.
  • reportschedule:read – read report schedules.

Webhooks

  • webhook:save – create or update webhook endpoints.
  • webhook:read – list or fetch webhook configurations.

Services/configuration

  • service:read – read service configuration data.
  • service:save – create or update service configuration.

Payment methods

  • paymentmethod:save – create or update payment methods (e.g., cards, SEPA mandates).
  • paymentmethod:read – read payment method details.

**Sales / transactions

  • sale:read – read sales / transaction information.
  • sale:save – create new sales (charges / payments) or update existing ones.
  • sale:refund – create refunds on existing sales.

Customers

  • customer:read – read customer profiles.
  • customer:save – create or update customer profiles.
  • customer:delete – delete customer profiles (where allowed).

3. Multi-tenant integrations (Currently in Beta)

In the multi-tenant scenario, a Third-Party App connects to multiple Buckaroo merchants. Each merchant explicitly grants access via My Buckaroo Portal. After consent, the Third-Party App receives an access token and a refresh token to call the Buckaroo API on behalf of that merchant.

3.1 Initial Authorization & consent

The following steps correspond to the first sequence diagram:

  1. User starts installation

In My Buckaroo Portal, the merchant clicks an “Install App” button for your Third-Party App.


  1. Portal starts authorization

The portal initiates an OAuth authorization flow with the Buckaroo Token API / Authorization Server, specifying:

  • the Third-Party App’s client_id
  • requested scope (space-separated)
  • redirect/callback information
  • optional state for CSRF protection

  1. User is prompted for consent

The merchant is shown a consent screen describing:

  • which Third-Party App is requesting access
  • which Buckaroo account (tenant) will be connected
  • which scopes (permissions) are requested

  1. User confirms consent

Once the merchant accepts, the authorization server issues:

  • an access_token (short-lived)
  • a refresh_token (long-lived) bound to:
  • the Third-Party App (client)
  • the merchant’s Buckaroo account (tenant)
  • the approved scopes

  1. Portal shares tokens with the Third-Party App

The Token API sends the access_token and refresh_token to the Third-Party App (for example via a secure backend-to-backend call or redirect with an authorization code + token exchange, depending on your final implementation).


  1. Third-Party App calls Buckaroo API

The Third-Party App now calls Buckaroo endpoints on behalf of the merchant:

 GET /resource
 Authorization: Bearer {access_token}

The Buckaroo API validates the token and returns the protected Buckaroo resource. The Third-Party App must store (and encrypt) the refresh_token per merchant tenant so it can renew access later.



3.2 Refreshing an expired access token

Access tokens are intentionally short-lived. When an access_token expires, the Third-Party App should use the refresh token to obtain a new one. This corresponds to the second sequence diagram.

Call the token endpoint with grant_type=refresh_token
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token={REFRESH_TOKEN}
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
Receive a new access token

The Buckaroo Authorization Server returns a new access_token and optionally a new refresh_token:

{
  "access_token": "new-access-token...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "new-or-existing-refresh-token..."
}

The Third-Party App should:

  • update the stored tokens for that merchant tenant
  • continue using the new access_token for API calls
  1. Call the Buckaroo API with the new token
  2. GET /resource
  3. Authorization: Bearer new-access-token...
  4. Receive the protected resource

The Buckaroo API returns the requested protected resource. If the refresh token is invalid or revoked (for example, if the merchant uninstalls the app or withdraws consent), the token endpoint will return an error. In that case the Third-Party App must stop calling the API for that tenant and may prompt the merchant to reconnect.


  1. Best practices
  • Use HTTPS everywhere when handling client credentials, access tokens and refresh tokens.
  • Store secrets securely (e.g. in a secrets manager or encrypted storage; never in client-side code or logs).
  • Use least privilege: request only the scopes you actually need.
  • Handle revocation: be prepared for refresh-token failures and clean up tenant connections gracefully.
  • Log and monitor token errors to detect configuration issues or abuse early.

Updated about 4 hours ago