Skip to main content

Token Management

warning

Your initial partner tokens have a short lifetime and will expire! Create a new partner token with a long lifetime and at least the partner:update scope, to be able to create new tokens with updated scopes. If all your partner tokens with the partner:update scope expire, you must contact the PayData support to obtain a new token!

Partners can manage their own, child-partner and user tokens using the various token endpoints.

Master Token Creation​

PayData recommends creating a master token that is then stored in a secure place, like a key management system, which has reminders for key-rotations. This master token should not be used for normal operation.

The following request creates a new token with a 1 year lifetime and the partner:update scope that is required to create new tokens, plus partner:read so the same token can also list and manage existing tokens (see below). See scopes for the available scopes.

POST /partners/self/tokens
CreateOwnPartnerToken
POST /partner/v2/partners/self/tokens HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer <INITIAL PARTNER TOKEN>
Content-Type: application/json
Request Body
{
  "name": "Master Token",
  "expiresIn": 31536000,
  "scope": "partner:read partner:update"
}
Response — HTTP/1.1 200
{
  "id": "j2r27hmn61",
  "name": "Master Token",
  "createdAt": "2024-03-29T07:32:13.9396933Z",
  "expiresIn": 31536000,
  "expiresAt": "2025-03-29T07:32:13.9396933Z",
  "isRevoked": false,
  "isExpired": false,
  "isValid": true,
  "scope": "partner:read partner:update",
  "lastUsedAt": null,
  "revokedAt": null,
  "accessToken": "{MasterToken}"
}
info

partner:update alone is enough to create new tokens, but the GetOwnPartnerTokens call below also needs partner:read (or partner:all) — a master token created with only partner:update will get a 403 Forbidden when you try to list tokens with it. Include both scopes so the same master token can do everything in this section.

Using the master token, you should then check the available tokens for your partner and revoke the initial token PayData issued to you.

GET /partners/self/tokens
GetOwnPartnerTokens
GET /partner/v2/partners/self/tokens HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer <MASTER TOKEN>
Response — HTTP/1.1 200
{
  "tokens": [
    {
      "id": "hg61ya38rz",
      "name": null,
      "createdAt": "2024-01-15T09:00:00.0000000Z",
      "expiresIn": 3600,
      "expiresAt": "2024-01-15T10:00:00.0000000Z",
      "isRevoked": false,
      "isExpired": true,
      "isValid": false,
      "scope": "partner:update",
      "lastUsedAt": "2024-01-15T09:05:00.0000000Z",
      "revokedAt": null
    },
    {
DELETE /partners/self/tokens/hg61ya38rz
RevokePartnerOwnToken
DELETE /partner/v2/partners/self/tokens/hg61ya38rz HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer <MASTER TOKEN>
Response — HTTP/1.1 204

This ensures that you are in control of the issued tokens and your initial token is not accidentally leaked because it was shared or stored somewhere insecure.

info

You cannot lock yourself out using token revocation as you cannot revoke the token you are using to access the API.

Having multiple tokens with short expiry timestamps and limited scopes like this increases the security of your application, since the master token itself is never shared with every service that needs to call the API — see Partner Tokens below for the day-to-day tokens you mint from it.

Partner Tokens​

The partner tokens are the most important tokens, as they grant administrative access to your partner, which includes access to all child-partners, users, accounts and transactions.

Partner tokens have scopes that limit the access of said token to specific resources and actions. See scopes for scopes that are valid for partner tokens.

note

Depending on the permissions, a partner token can also be used to directly access or even manage accounts without creating a user or requesting a user token — though not every operation accepts a partner token, see Authentication.

warning

Keep your partner tokens secret and don't make them available to on-premise systems or users as they might allow them to access resources that they're not allowed to access. An exception is deploy tokens.

By using a partner token, the tokens of the current or any child-partner can be managed using the following endpoints:

Or for child-partners:

These endpoints allow for the creation of multiple tokens per partner with the lifetime and scopes that are required.

Deploy Tokens​

A deploy token is a partner token with only the partner:create scope. By just using this scope, this token only allows the creation of new child-partners but it cannot access the main partner or other child-partners. This token can be made available to on-premise systems to allow them to create and manage their own child-partners and users.

The default lifetime of a child-partner's tokens is 6 months. The child-partner must create a new token during that time or a long-lived token immediately after the child-partner was created.

warning

The on-premise must manage its own tokens to avoid losing access to the API. If the on-premise system loses access, only the main partner can issue a new child-partner token.

User Tokens​

User tokens are issued when a new user is created and must be refreshed regularly using a partner or child-partner token — see Create user tokens for the request/response walkthrough.

To create new user tokens, the partner must use the CreateUserToken method.

User tokens have scopes that limit the access of said token to specific resources and actions. See scopes for scopes that are valid for user tokens.

A user token can also be handed directly to the end user it belongs to, letting them access the PayData API themselves rather than only through your partner software.

Scopes​

Scopes in PayData follow the format {resource}:{action} where {resource} is a resource made available though the API and {action} is one of all, read, create, update or delete.

Table of scopes
ScopeApplicable Token TypeToken CreationDescription
partner:allPartner, Child-PartnerPartnerPerform all actions on the partner and child-partners.
partner:readPartner, Child-PartnerRead partner information, including listing of child-partners.
partner:createPartner, Child-PartnerChild-PartnerCreate new child-partners and tokens for child-partners.
partner:updatePartner, Child-PartnerPartnerUpdate partner information, including child-partners, creation of own partner tokens.
partner:deletePartner, Child-PartnerDelete child-partners.
user:allPartner, Child-PartnerUserPerform all actions on users.
user:readPartner, Child-PartnerRead and list user information.
user:createPartner, Child-PartnerUserCreate new users and user tokens.
user:updatePartner, Child-PartnerUpdate users.
user:deletePartner, Child-PartnerDelete users.
account:allPartner, Child-Partner, UserPerform all actions on accounts.
account:readPartner, Child-Partner, UserRead and list1 accounts.
account:createPartner2, Child-Partner2, UserCreate and authorize new accounts.
account:updatePartner, Child-Partner, UserUpdate accounts and their credentials.
account:deletePartner, Child-Partner, UserDelete accounts.
transaction:allPartner, Child-Partner, UserPerform all actions on transactions.
transaction:readPartner, Child-Partner, UserRead and list transactions.

Footnotes​

  1. Listing accounts is currently not possible when using a partner token. ↩

  2. When creating an account with a partner token, an internal, technical user is created. This user is hidden and deleted when the account is deleted. ↩ ↩2