Docs
Checking Raims account
Integrations

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

  1. 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.

  2. 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.

  3. 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.

  4. Restrict the source when possible

    If the system uses fixed outbound addresses, allow only those IPv4 addresses or CIDR ranges.

  5. 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.

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:

.env.example
.env
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.

ResultWhat to check
HTTP 200, including an empty listThe read is authorized in that company and environment.
403 API_KEY_PERMISSION_DENIEDThe key does not grant this action. Review its saved permissions.
A later creation request is refusedRead permission does not grant creation. Add that access only if the integration needs it.

Choose the change you need

ActionWhat changesWhat to update in the integration
Edit permissionsThe actions allowed by the keyReview access; the secret stays the same.
RenameThe name shown in the DashboardNo credential change.
RotateThe secret used to authenticate requestsReplace the old secret in every backend that uses it.
RevokeThe key stops authenticating requestsUse another valid credential if the integration must continue.

Edit permissions

  1. Go to Integration, API keys and open the actions for the key.
  2. Select Edit permissions and review the current access.
  3. Adjust the action selection and choose Save permissions.
  4. 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

  1. Go to Integration, API keys and open the actions for the key.
  2. Select Rename key, enter the new name, and confirm Rename key.
  3. 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

  1. Go to Integration, API keys and open the actions for the correct key.
  2. Select Rotate key token, check the notice, and confirm Rotate token.
  3. Copy and store the new secret before closing the dialog.
  4. 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

  1. Go to Integration, API keys and open the key's actions.
  2. Select Manage IP restrictions.
  3. Add, edit, or remove only the IPv4 addresses and CIDR ranges used by your system. Check the confirmation for each change.
  4. 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

  1. Go to Integration, API keys and open the actions for the key you want to disable.
  2. Select Revoke API key, check the identified token, and confirm Revoke key.
  3. 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.

Account and checkout actions

Balance queries

Statement queries

Customer actions

Charge actions

Refund actions

Withdrawal actions

Dispute queries

Webhook actions

Simulation actions

Webhooks

Configure notifications and secrets separately from API keys.

Users and permissions

Separate access to keys and logs, creation, rotation, revocation, and IP management.

Start here

Prepare your Sandbox credential and learn how to use the API console.