Token API

      Token API

        Article Summary

        The Token API is designed to provide secure authentication and authorization for external systems that wish to perform actions on different Buckaroo services.

        With the Token API, merchant applications can use their own credentials to obtain a JWT token. This token can then be used to access and interact with specific Buckaroo web services, making transactions and operations smoother and more efficient.

        Here's how it works:

        Registration: As a merchant, you can register your application at the Plaza. To do so, visit the Configuration > Token Applications page. During registration, you can set the scopes that your application should be allowed to request tokens for. Each scope consists of an "audience" (the web service you want to use) and an "operation" (the action you want to perform).

        Credentials Generation: Once you have registered your application and defined the scopes, we will generate a client ID and secret key for the application to be used. These credentials will uniquely identify your application and enable it to request tokens from the Token API.

        Token Request: Armed with your client ID and secret key, your application can now request a JWT token from our Token API. This token is valid for 24 hours and serves as its authentication to access the specified web services and perform the authorized operations.

        Steps to create a new Application:

        1. Head to Configuration -> Token Applications.
        2. Click Register new application (top right corner).


        1. Fill in ‘Name’ and select Scopes.


        1. Click "Save"
        2. After a successful addition, the new application will now appear at the end of the list.

        Steps to update an Application:

        1. Click on the application you want to update.

        2. Then, click ‘Edit’ on top right corner.

        3. Now you can see that ‘Name’ and ‘Scopes’ are editable.

        4. Update Name or Scopes and click "Save" .

        5. After a successful update, the application will have a new updated Name and Scopes.

        External Api Endpoints

        The endpoints of the external api are as follows:

        GET oauth/token

        Use Basic Authentication header with the client ID and secret.

        Request Body:
        Grant type: The type of grant being requested, should be 'client_credentials'.
        Scopes: The requested scopes, space-separated with audience:operation format.


        200 Ok: Returns the requested JWT token.


        401 Unauthorized: Unauthorized if the client ID and client secret are invalid.

        400 Bad Request in the following cases:
        • Grant type is not 'client_credentials'.
        • No scopes are given in the request.
        • The scopes requested are not linked to the application that requests the token.

        How to use the token

        When making an HTTP request with Bearer Token authorization, you should include the token in the "Authorization" header as follows: "Authorization: Bearer {token}".


        Authorization: Bearer BEARER_TOKEN_HERE
        Content-Type: application/json

        Was this article helpful?

        What's Next