API credentials

Introduction

When starting to work with Payrails, one of the first steps is obtaining your API credentials for your account to authenticate Payrails APIs. Our system requires authentication to ensure that only authorized users or systems can access our API, thereby helping us protect sensitive data, prevent misuse, and maintain the integrity of our services.

Your API credentials will be created and managed in the Payrails Portal. Client ID and Client Secret are the API credentials you need to start interacting with the Payrails API, both in staging and production environments.

You have the flexibility to create as many API credential sets as you need, and you can create them both on the organization level or at a specific workspace level, depending on your needs.

Obtaining your API credentials

Only admin and developer roles can access the API credentials page. Check here for (roles & permissions) for more information.

1. Log in to your Payrails Portal,
2. Navigate to the System Configurations>API Credentialspage,
3. Create API credentials by following the instructions on the page,
4. Copy the client ID and client secret,
5. Use credentials in your system to request an access token from Payrails to be used in all Payrails API endpoints.

Rotating your client secret

You may want to rotate the previously generated client secret.

1. Navigate to the System Configurations>API Credentialspage,
2. Select the client ID that you wish to rotate its client secret to rotate it,
3. Copy the new client secret,
4. Use the new secret in your system to request an access token from Payrails to be used in all Payrails API endpoints.

After rotation, the previous client secret becomes invalid immediately.

Note that you can have multiple client IDs and secrets can be used at a time to ensure uninterrupted access to the Payrails API.

Important notes

• API keys should be as restrictive as possible. Internally, keep track of which systems/users have access to it.
• Pay attention to the one-time display of the client secret during the creation and rotation process.
• Ensure to update your application immediately with the new client secret to avoid any disruption in API access.
• The previous client secret becomes invalid once rotated and should not be used for further API requests.
• Once an access token is generated, the standard TTL is 1 hour, after which the token has to be regenerated.
• There are no upper limits for generating an access token. You can generate as many as necessary for a given client ID and secret.