Token Management
Your initial partner tokens has 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.
- List own tokens
- Create own token
- Revoke own token
- List child-partner tokens
- Create child-partner token
- Revoke child-partner token
- Create user token
Master Token Creation
We recommend the creation of 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. See scopes for the available scopes.
curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/partners/self/tokens' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <INITIAL PARTNER TOKEN>' \
--data-raw '{
"name": "Master Token",
"expiresIn": 31536000, // 1 year
"scope": "partner:update"
}'
Using the master token, you should then check the available tokens for your partner and revoke the initial token issued by us.
curl -L -X GET 'https://api-sandbox.paydata-api.com/partner/v2/partners/self/tokens' \
-H 'Authorization: Bearer <MASTER TOKEN>'
curl -L -X DELETE 'https://api-sandbox.paydata-api.com/partner/v2/partners/self/tokens/:tokenId' \
-H 'Authorization: Bearer <MASTER TOKEN>'
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.
You cannot lock yourself out using token revocation as you cannot revoke the token you are using to access the API.
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.
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 exceptions are deploy tokens.
By using a partner token, the tokens of the current or any child-partner can be managed using the following endpoints:
- GetOwnPartnerTokens: List tokens for the current partner.
- CreateOwnPartnerToken: Create token for the current partner.
- RevokePartnerOwnToken: Revoke token for the current partner.
Or for child-partners:
- GetPartnerTokens: List tokens for a child-partner.
- CreatePartnerToken: Create token for a child-partner.
- RevokePartnerToken: Revoke token for a child-partner.
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 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.
The on-premise must manage it's 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.
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.
Security
Having multiple tokens with short expiry timestamps and limited scopes can increase the security of your application as the master token must not be shared with every service.
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
| Scope | Applicable Token Type | Token Creation | Description |
|---|---|---|---|
partner:all | Partner, Child-Partner | Partner | Perform all actions on the partner and child-partners. |
partner:read | Partner, Child-Partner | Read partner information, including listing of child-partners. | |
partner:create | Partner, Child-Partner | Child-Partner | Create new child-partners and tokens for child-partners. |
partner:update | Partner, Child-Partner | Partner | Update partner information, including child-partners, creation of own partner tokens. |
partner:delete | Partner, Child-Partner | Delete child-partners. | |
user:all | Partner, Child-Partner | User | Perform all actions on users. |
user:read | Partner, Child-Partner | Read and list user information. | |
user:create | Partner, Child-Partner | User | Create new users and user tokens. |
user:update | Partner, Child-Partner | Update users. | |
user:delete | Partner, Child-Partner | Delete users. | |
account:all | Partner, Child-Partner, User | Perform all actions on users. | |
account:read | Partner, Child-Partner, User | Read and list1 accounts. | |
account:create | Partner2, Child-Partner2, User | Create and authorize new accounts. | |
account:update | Partner, Child-Partner, User | Update accounts and their credentials. | |
account:delete | Partner, Child-Partner, User | Delete accounts. | |
transaction:all | Partner, Child-Partner, User | Perform all actions on transactions. | |
transaction:read | Partner, Child-Partner, User | Read and list transactions. |