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

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    Content type and encoding of the request.

    • Example: application/x-www-form-urlencoded
  • Name
    Authorization
    Type
    String
    Tag(s)
    Mandatory
    Description

    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

  • Name
    data-urlencode
    Type
    String
    Tag(s)
    Mandatory
    Description

    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

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    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.

  • Name
    refresh_token_expires_in
    Type
    String
    Tag(s)
    Mandatory
    Description

    Always returned as '0'.

  • Name
    api_product_list
    Type
    String
    Tag(s)
    Mandatory
    Description

    This is the list of products currently active.

  • Name
    api_product_list_json
    Type
    Array of Strings
    Tag(s)
    Mandatory
    Description

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

  • Name
    organization
    Type
    String
    Tag(s)
    Mandatory
    Description

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

  • Name
    developer.email
    Type
    String
    Tag(s)
    Mandatory
    Description

    The email address associated with this API key.

  • Name
    token_type
    Type
    String
    Tag(s)
    Mandatory
    Description

    This is the type of token issued.

    • Example: BearerToken
  • Name
    issued_at
    Type
    String
    Tag(s)
    Mandatory
    Description

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

  • Name
    client_id
    Type
    String
    Tag(s)
    Mandatory
    Description

    The client_id as passed in the request.

  • Name
    access_token
    Type
    String
    Tag(s)
    Mandatory
    Description

    This is the access token issued.

  • Name
    application_name
    Type
    String
    Tag(s)
    Mandatory
    Description

    The id associated to the application making the request.

  • Name
    scope
    Type
    String
    Tag(s)
    Optional
    Description

    The scope for this token.

  • Name
    expires_in
    Type
    String
    Tag(s)
    Mandatory
    Description

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

    • Example: 3599
  • Name
    refresh_count
    Type
    String
    Tag(s)
    Mandatory
    Description

    Always returned as '0'.

  • Name
    status
    Type
    String
    Tag(s)
    Mandatory
    Description

    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