POST/oauth/client_credential/accesstoken

Auth Specification

This document provides essential information on how to make a successful request using the Auth API. The API enables secure access to our services by requiring authentication credentials. To interact with our APIs, we support OAuth 2.0 client credentials with basic authentication. This ensures secure and controlled access to protected resources. For details on the OAuth 2.0 client credentials flow, refer to the official specification: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4

Additionally, we provide a Postman collection that includes a sample Authorization API call. You can download and import the collection into Postman to quickly set up and test authentication requests.

In the following sections, you will find details on authentication requirements, request structure, and best practices for securely integrating with the Authorization API.

Document History

VersionDateDescription
1.015 Jan 2025Original Digital Version. Aligned with PDF V1.3
2.020 Mar 2025Format changes. Refer to the detailed changes here.

Endpoints

EnvironmentEndpoint URL
SandboxAvailable on request
ProductionAvailable on request

Go directly to

How does it work?

You need an access token to use the API. To obtain an access token you need to call the Auth API. The OAuth 2.0 specifications recommend passing the client_id and client_secret values as an HTTP-Basic Authentication header. Don't have credentials yet? You can request them in the top right of this portal under the button "Get API keys".

Your client_id and client_secret need to be base64 encoded before you can send them in the header.

In pseudo-code:
result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':','ZIjFyTsNgQNyxI'))

In this example, ns4fQc14Zg4hKFCNaSzArVuwszX95X is the client_id and ZIjFyTsNgQNyxI is the client_secret.

The result being: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJ==

Request

Request Headers

  • Content-TypeStringMandatory

    Content type and encoding of the request.

    • Example: application/x-www-form-urlencoded
  • AuthorizationStringMandatory

    Basic authentication - base64 encoded client_id and client_secret.

Example of Request Headers

Header nameExample
Content-Typeapplication/x-www-form-urlencoded
AuthorizationBasic <your basic token>

Request Body

  • data-urlencodeStringMandatory

    We only support the grant_type: client_credentials.

    • Example: grant_type=client_credentials

Request Curl example

curl --location --request POST '<hostValueWillBeSharedBySurePay>/oauth/client_credential/accesstoken' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <your basic token>' \
--data-urlencode 'grant_type=client_credentials'

Response

Response Headers

  • Content-TypeStringMandatory

    Content type and encoding of the request.

    • Example: application/json

Example of Response Headers

Header nameExample
Content-Typeapplication/json

Response Body

On a succesfull request, you will receive an access_token as well as some other information about your customer profile, your products, when your token was issued and after how many seconds it expires. At SurePay we do not work with refresh_tokens and therefore you cannot refresh this token. It is advised to make another API call with basic authentication to fetch a new access_token when this one expires.

  • refresh_token_expires_inStringMandatory

    Always returned as '0'.

  • api_product_listStringMandatory

    This is the list of products currently active.

  • api_product_list_jsonArray of StringsMandatory

    This is the list of products currently active as an array of strings.

  • organizationStringMandatory

    The organization's name as registered within SurePay's VoP platform.

  • developer.emailStringMandatory

    The email address associated with this API key.

  • token_typeStringMandatory

    This is the type of token issued.

    • Example: BearerToken
  • issued_atStringMandatory

    The time the access token was issued. This refers to the milliseconds since the epoch, which is 1 Jan 1970 UTC.

  • client_idStringMandatory

    The client_id as passed in the request.

  • access_tokenStringMandatory

    This is the access token issued.

  • application_nameStringMandatory

    The id associated to the application making the request.

  • scopeStringOptional

    The scope for this token.

  • expires_inStringMandatory

    When the access token expires. Configurable on SurePay's side, default is 1 hour.

    • Example: 3599
  • refresh_countStringMandatory

    Always returned as '0'.

  • statusStringMandatory

    The status of the request.

Response example

{
    {
        "refresh_token_expires_in": "0",
        "api_product_list": "[Account Check V2 - Banks - Acc]"
        "api_product_list_json": [
            "Account Check V2 - Banks - Acc"
        ],
        "organization_name": "SurePay",
        "developer.email": "service@surepay.nl",
        "token_type": "BearerToken",
        "issued_at": "1693214579017",
        "client_id": "<your client ID>",
        "access_token": "<your bearer token>",
        "application_name": "8ce4bc06-07c2-4e4e-9dfe-1234567ef7d3",
        "scope": "",
        "expires_in": "3599",
        "refresh_count": "0",
        "status": "approved"
    }
}
Previous
Next