API keys
Create, protect, and manage integration credentials in the Dashboard.
The Integration, API keys area manages the credentials used to connect your company's system to Raims. Sandbox and Production keys belong to separate environments and must not be reused between them.
Viewing keys requires API keys. Creating, rotating, renaming, editing access, revoking, and managing IPs have their own permissions. These actions may also be blocked when the account is in view-only mode. Use these credentials to authenticate requests to the Raims API.
The key's access is always defined by its saved selection. An empty selection does not authorize any API operation.
Viewing logs also requires View request logs. This access allows you to read the details and request and response bodies available in the history. Access to keys does not automatically grant access to logs. See how to grant this permission to your team.
Keep the key secret
Never put a Raims key in a browser, distributed apps, repositories, screenshots, or logs. Keep the credential in the private part of the system responsible for the integration.
Create a key
Open API keys
Go to Integration, API keys, Create new API key with Create API keys. Check the selected environment before creating the key. If prompted, confirm your identity to open the form. Accounts without access to Production can create Sandbox keys only.
Give it an operational name
Enter the Key name and check the Key type. Use a name that identifies the system and environment, such as ERP - Sandbox or Main integration - Production.
Choose access
In API permissions, select only the actions the integration needs. Viewing, creating, updating, deleting, and other actions have independent selections. Use Learn more to check what each action allows. The selection starts empty.
Restrict the source when possible
If the system uses fixed outbound addresses, allow only those IPv4 addresses or CIDR ranges.
Copy and store it immediately
After completing the form, select Create. Complete identity confirmation when requested; creation continues automatically without another click on Create. Copy the displayed secret and save it in a secrets vault before closing the dialog.
Separate environments
Test keys use placeholders such as sk_test_... and are for development and
integration testing. They do not process real money.
Production keys use placeholders such as sk_live_... and can authorize
requests with real effects on the account. Use them only after the
integration has been approved and is ready for Production.
The API reference presents authentication, fields, and examples for each request. The console accepts Sandbox keys for testing the integration.
Secure storage
Use a secrets manager or a protected variable in the environment where the integration runs. Example files must contain only the variable name:
RAIMS_API_KEY=sk_test_...Do not commit a real .env file. Limit access to the people and systems
that need to use the integration.
Key permissions
Each key has a selection of API actions. You can allow creating a charge without allowing queries, updates, revocations, or refunds. Selecting an action does not automatically grant the other actions for that resource.
Account and environment rules still apply. Key permissions are separate from an employee's permissions to manage the key in the Dashboard. The tables below explain each action offered in the matrix and its Learn more link.
To copy a Sandbox key's secret or rotate a key, an employee must have access to every resource and action it allows. When a key grants access beyond their own, it remains in the list with its secret hidden, and copying and rotation are unavailable. Ask an authorized person to review the key; viewing its metadata does not grant access to the secret.
Example: a read-only customer integration
If the backend only lists and retrieves customers, select View customers. You do not need customer creation, editing, or removal for those reads. Create the key in Sandbox, store it on the server, and use the complete authentication example.
| Result | What to check |
|---|---|
HTTP 200, including an empty list | The read is authorized in that company and environment. |
403 API_KEY_PERMISSION_DENIED | The key does not grant this action. Review its saved permissions. |
| A later creation request is refused | Read permission does not grant creation. Add that access only if the integration needs it. |
Choose the change you need
| Action | What changes | What to update in the integration |
|---|---|---|
| Edit permissions | The actions allowed by the key | Review access; the secret stays the same. |
| Rename | The name shown in the Dashboard | No credential change. |
| Rotate | The secret used to authenticate requests | Replace the old secret in every backend that uses it. |
| Revoke | The key stops authenticating requests | Use another valid credential if the integration must continue. |
Edit permissions
- Go to Integration, API keys and open the actions for the key.
- Select Edit permissions and review the current access.
- Adjust the action selection and choose Save permissions.
- Complete the security confirmation when prompted.
This action requires Edit API keys. Editing preserves the key's secret; you do not need to replace the token in the integration. Grant only the access required. Your own access also limits which permissions you can grant.
If someone else changes the key while you edit it, load the current selection, review the differences, and save again. Do not confirm an old selection without checking the change.
A request without the required access receives 403 API_KEY_PERMISSION_DENIED.
Check the key's permissions before retrying. See
Authentication.
IP restrictions
The Dashboard accepts an individual IPv4 address, such as 203.0.113.10, or
a CIDR range, such as 203.0.113.0/24. Use only stable outbound addresses
confirmed by your infrastructure.
Enter the four decimal IPv4 numbers separated by periods, without leading
zeros. Each number must be between 0 and 255. For a CIDR range, add /
and an integer prefix from 0 to 32, with no sign or leading zeros.
The range includes the entire network indicated by the prefix. For example,
203.0.113.7/24 appears as 203.0.113.0/24 and covers 203.0.113.0 through
203.0.113.255. The /32 prefix appears as an individual IP. Entries that
represent the same range appear only once. Check the list before saving,
especially when entering a shorter prefix, which allows a larger range of
addresses.
Rename a key
- Go to Integration, API keys and open the actions for the key.
- Select Rename key, enter the new name, and confirm Rename key.
- Wait for confirmation and check the name in the list.
This action requires Edit API keys. It changes only the displayed name; existing integrations continue using the same secret.
Rotate a key
- Go to Integration, API keys and open the actions for the correct key.
- Select Rotate key token, check the notice, and confirm Rotate token.
- Copy and store the new secret before closing the dialog.
- Update the systems that used the previous token.
This action requires Rotate API keys. Employees must also have access to every resource and action granted by the key. Rotation replaces the previous secret; the key keeps the settings shown.
Manage IP restrictions
- Go to Integration, API keys and open the key's actions.
- Select Manage IP restrictions.
- Add, edit, or remove only the IPv4 addresses and CIDR ranges used by your system. Check the confirmation for each change.
- Use Download list if you need to save the configured addresses.
Changes require Manage API IPs. Read IP restrictions in this guide before defining a network range. An empty list leaves the key without source restrictions.
Revoke a key
- Go to Integration, API keys and open the actions for the key you want to disable.
- Select Revoke API key, check the identified token, and confirm Revoke key.
- Wait for Key revoked.
This action requires Delete API keys and revokes the key. Systems that still depend on that token must be updated with another valid credential.