Authentication

The Railz API uses API keys to authenticate requests. You can view and manage your API keys in the Railz Dashboard™.

API Keys Scopes

Scoping your API keys is a security practice that involves granting specific permissions and access levels to API keys based on the intended use case. Scoping API keys helps prevent unauthorized access to sensitive data and functionalities, enhances security, and ensures that each key is limited to its intended purpose. It's a good security practice to enable only the permissions you need, and not more.

API key scopes can be set from the Dashboard under the Developers Tab > API Keys section.

Scope NameDescriptionPermissions
Railz APIAccess to call the endpoints under the following categories:
- Common API
- Accounting API
- Banking API
- Commerce API
- Analytics API
Full (read/write)
Visualization SDKAccess to call the Visualization Report APIsRead

API Key Characteristics

  1. An access_token is valid for 60 minutes. We recommend getting a new access_token before calling each API endpoint.
  2. API keys for integrations do not expire, they have to be revoked by deleting them through the Dashboard to stop them from working.
  3. API keys for integrations are completely detached from the user that created them. They will not be revoked (deleted) even if the user who created them is deleted or their account is disabled.
  4. You are able to create a maximum of 5 keys per team.
  5. Sandbox mode secret keys have the prefix SB_ and Production mode secret keys have the prefix ID_.

❗️

Secure your API Keys

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication Flow

Authentication to the API is performed via HTTP Basic Authentication on the Get Access Token endpoint. Provide your API identifier client_id as the basic auth username and secret key secret_key as the password, Base64 encoded.

The response will provide you with an access_token that you can use with the endpoints described in this reference documentation.

🚧

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Railz expects the API key to be included in all API requests to the server with an Authorization header.

Authorization: Bearer your_api_key

Admin and Developer users can view and generate API keys from the Railz Dashboard™. You must replace your_api_key with your API key.

How to - User Guide