Authentication | Raims Documentation

The Raims API uses an API key to identify the company responsible for the request. Your application backend must send this key in the Authorization header, using the Bearer scheme, in every authenticated request.

Before you start

Create an API key for the environment your application will use. See API keys to obtain and manage the credential.

Store the secret in a secrets vault or a protected environment variable, accessible only to the backend responsible for the integration.

Protect your API key

Do not expose the key in frontend applications, distributed apps, images, logs, or repositories. Send the secret only in the authentication header, never in the URL or request body.

Authentication header

Configure your backend HTTP client with the following headers when sending a JSON body:

{
  "Authorization": "Bearer SUA_CHAVE_API",
  "Content-Type": "application/json"
}

Header	Usage
`Authorization`	Required for authenticated requests. Use `Bearer` followed by a space and the complete key.
`Content-Type`	Send `application/json` when the request has a JSON body.

GET requests must use the parameters defined by the endpoint and have no body. The key identifier, a masked secret, or a Dashboard login credential cannot replace the API key.

Use HTTPS for API calls. Send the secret exactly as generated, without changing letters or adding characters.

Sandbox and Production

The base URL is the same in both environments:

https://api.raims.com

The key sent in the Authorization header determines the environment and company. Do not send an additional field in the URL or body to choose the environment.

Environment	Key prefix	Usage
Sandbox	`sk_test_`	Development and integration testing, with test data separate from Production data.
Production	`sk_live_`	Requests with real effects on the account, sent by your backend.

Validate the integration in Sandbox before using Production. To change environments, update the key configured in your backend and check the data and identifiers being sent. Changing the credential does not move a resource created in Sandbox into Production.

IP restrictions

If the key has IP restrictions, requests must originate from an authorized address. Configure the public outbound IP of the server or infrastructure running your backend, including the authorized ranges when using CIDR.

See IP restrictions to configure the allowed ranges.

Authentication errors

A 401 Unauthorized response means the request could not be authenticated. Check that:

Authorization contains Bearer, a space, and the complete key;
the key is correct, with no extra characters or missing parts;
the credential belongs to the intended company and environment;
the key remains valid and has not been revoked or replaced through rotation.

After rotating a key, update your backend configuration with the new secret. The previous key no longer authenticates requests.

A 403 Forbidden response may indicate an IP restriction, an account condition, or another authorization rule. A valid key does not allow a request blocked by those conditions.

COMPANY_STATUS_RESTRICTED means the company's status prevents access. Suspended companies or companies with a closed account cannot use the API in either environment. A pending registration allows Sandbox only. The message identifies the condition and directs you to Customer Service or to check the registration in the Dashboard.

See HTTP response codes to interpret the status, code, and message returned by the API.