Tokens

To authorize API requests, you use an access token. If you use the Authorization Code flow, you also receive a refresh token to obtain new access tokens. Access tokens are the proof of authorization that our API requires. They must be added to the Authorization header of each request to the Payt API. Each time you need a new access token, you must use the refresh token to request a new one. If your refresh token expires, the user needs to authorize your app again. In order to prevent this, a new refresh token is returned each time a new access token is created. This way your app remains authorized as long as it is used frequently.

Token	Expiry	Notes
Access token	2 hours	Must be refreshed using the refresh token after expiry.
Refresh token	90 days	Rotated on every use; a new refresh token is returned each time you create an access token.

As long as your app requests a new access token at least once every 90 days, the refresh token never expires in practice.

Create tokens

A new set of tokens can be created by sending a request to the token endpoint (/oauth/token) using the last received refresh token. The very first refresh token is received during the confirmation step of the authorization process. Request:

POST https://api.paytsoftware.com/oauth/token
Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0

{
  "grant_type": "refresh_token",
  "refresh_token": "PKWuvzHNj3ALI0G7QNBGjBI1-q3aMLZBqgXdaaumk18"
}

curl --header 'Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0' \
--form 'grant_type=refresh_token' \
--form 'refresh_token=PKWuvzHNj3ALI0G7QNBGjBI1-q3aMLZBqgXdaaumk18' \
--request POST https://api.paytsoftware.com/oauth/token

Header	Presence	Definition
`Authorization`	required	Basic

Parameter	Presence	Definition
`grant_type`	required	Must be: `refresh_token`.
`refresh_token`	required	Must be the last refresh token received.

Response:

{
  "access_token": "2GyChYPFxhYOis/uiLoVkA==",
  "created_at": 1577836800,
  "expires_in": 7200,
  "refresh_token": "PKWuvzHNj3ALI0G7QNBGjBI1-q3aMLZBqgXdaaumk18",
  "scope": "invoices:read debtors:read",
  "token_type": "Bearer"
}

Key	Value
`access_token`	The token that can be used to authenticate API requests.
`created_at`	The UNIX time at which the token was created.
`expires_in`	The number of seconds the access token is valid.
`refresh_token`	The new refresh token, must be used to create the next token.
`scope`	List of granted permissions.
`token_type`	Will always be `Bearer`.

Introspect a token

Besides the scopes that are granted, you might want to know for which company and which administrations of this company the authorization was granted. This information can be retrieved by sending an active token (either an access token or refresh token) to the introspect endpoint. Request

POST https://api.paytsoftware.com/oauth/introspect
Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0

{
  "token": "IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8"
}

curl --header 'Authorization: Basic cS1ReW5uYkREWFZGSkNIVVBnNThFV0hIMm41a0NXYVdZZUo1bFZRTkk3QTpNcTRFMlZGTnNzcjVpQTdaN0xBZFM4MnZtNTl3Qm9nNVE1SGw2Si1Pc0w0' \
--form token=IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8 \
--request POST https://api.paytsoftware.com/oauth/introspect

Response

{
  "active": true,
  "administrations": [
    {
      "id": "123",
      "name": "Administration Name"
    },
    {
      "id": "321",
      "name": "Administration Two Name"
    }
  ],
  "client_id": "q-QynnbDDXVFJCHUPg58EWHH2n5kCWaWYeJ5lVQNI7A",
  "company": {
    "id": "123",
    "name": "Company Name"
  },
  "exp": 1577844000,
  "iat": 1577836800,
  "scope": "invoices:read debtors:read",
  "token_type": "Bearer"
}

Key	Value
`active`	Whether the access token (not the refresh token) is still valid.
`administrations`	List of administration ids and names the token is granted access to.
`client_id`	The client_id of the application.
`company`	The id and name of the company the token is granted access to.
`exp`	The UNIX time at which the access token (not the refresh token) will expire.
`iat`	The UNIX time at which the token was created.
`scope`	List of granted permissions.
`token_type`	Will always be `Bearer`.

If the given token has expired, does not belong to your client or does not exist, the following response will be returned: Response:

{
  "active": false
}

Use an access token / static API token

To query the Payt API an active access token must be added to the Authorization header, preceded by Bearer:

GET https://api.paytsoftware.com/v1/invoices?administration_id=123
Authorization: Bearer IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8

curl https://api.paytsoftware.com/v1/invoices?administration_id=123 \
--header 'Authorization: Bearer IBzLDErQvt9gOmSLarUtDy06emduHZmKEG2OSPdHpJ8'

Introduction

API endpoints

Create tokens

Introspect a token

Use an access token / static API token

​Create tokens

​Introspect a token

​Use an access token / static API token

Create tokens

Introspect a token

Use an access token / static API token