Authentication

API token authentication

Authenticate to the Payabli API with an API token sent in the requestToken header
View as MarkdownOpen in Claude
Applies to:Developers

Payabli API tokens are long-lived tokens you send in the requestToken header. Payabli also supports OAuth2 Bearer tokens, which are recommended for new integrations. See OAuth authentication.

Note that API tokens are different than payment method tokens. API tokens are used for authentication, while payment method tokenization exchanges sensitive payment method information for secure tokens.

Your API tokens carry privileges, so keep them secure. Don’t share your private API tokens in public areas such as GitHub, client-side code, or public domains.

When you authenticate to the API, send the API token in the request header with the key requestToken.

Example header
$  curl -X POST 'https://api-sandbox.payabli.com/api/Endpoint' \
>      -H 'accept: application/json' \
>      -H 'content-type: application/*+json' \
>      -H 'requestToken: YOUR_API_TOKEN'

You must make all API requests over HTTPS. API requests without authentication will fail.

Create and manage API tokens

You can create and manage your own API tokens in the Payabli Portal.

  1. Navigate to Developers > API Tokens, then click Create API Token.
  2. In the modal, configure your API token. See the configuration options table below.
  3. When finished, save your work.
Configuration optionDescription
Token ModePublic tokens are for embedded components, including Creator components. Private tokens are for Payabli APIs and payment devices.
Token TypeThe organization API token type is the most commonly used, and gives partners and paypoints access to most endpoints. The application API token is more advanced, and is used for authentication and managing entities. You rarely need to use an application API token. See the API token types section for more information.
Token LifetimeAPI tokens can have a lifetime of between 1 and 24 months. Remember that you can delete unused or compromised API tokens at any time from the dashboard.
IP RestrictionsUse this option to create an allowlist of IP addresses that can make requests with this API token. Leaving this option blank allows all IP addresses to make requests with this API token.
Creator Token?Select Yes to use this API token with Creator components. The API token type must be Public. Creator API tokens require that you configure domain restrictions.
Domain RestrictionsOnly available with Creator API tokens. For security, you must add the domains that you embed Creator components on. For example, if they’re embedded on https://app.myproduct.com, then add https://app.myproduct.com here.
DescriptionA descriptive name for the API token. This description appears in the dashboard and helps identify the API token.

To view or delete API tokens, navigate to Developers > API Tokens, then click the Action column of a token you want to manage.

API token types

To enhance security, Payabli has several different types of API token, each with different scopes and lifetime.

The organization token is the most basic and most commonly used API token used in the platform. Any organization or paypoint with an organization token has access to most API functions and endpoints. You can view and manage these API tokens in the Payabli Portal.

Payabli has two kinds of organization API tokens:

  • Private Token: Private tokens are for making API calls and have the highest level of security.
  • Public Token: Public tokens are for adding Payabli’s embeddable components in your user interface. These tokens are publicly readable.

You can’t access API endpoints related to management and authentication services for users with an organization token. To access those services, you need an application token.

The Payabli team generates application API tokens for partners that are using API endpoints for authentication and managing entities. For example, you need this kind of token if you are building your own portals for paypoints, or any solution that involves users authenticating to Payabli outside of the Payabli Portal or a PayHub.

If you are working outside of a PayHub or the Payabli Portal, the Payabli API requires you to retrieve a user API token before performing certain actions. These tokens add an extra layer of security for managing paypoints, managing users stored in Payabli, getting access to merchant documents, and using authentication services. If you are performing these activities within the Payabli Portal or a PayHub, you don’t need to generate this token.

You need an application API token to generate a user API token.

User API tokens are valid for 120 minutes after creation, but expire after 1800 seconds (30 minutes) of inactivity.

To generate a user API token you need:

  1. Application API token (provided by the Payabli team to the Partner or Merchant).
  2. User email and user password (the user’s Payabli login credentials).
$curl -L -X POST 'https://api-sandbox.payabli.com/api/User/auth' \
>-H 'requestToken: a.thisistheapplication.token' \
>-H 'Content-Type: application/json' \
>-H 'Accept: application/json' \
>-d '{
>  "email": "useremail@here.com",
>  "psw": "xxxxxxxxxx"
>}'

Temporary API tokens are generated by services or endpoints related mainly to resetting passwords, multi-factor authentication (MFA), and activities without authentication that require approved security levels, like payment pages. Temporary tokens can be used for only one request in specific endpoints.