Skip to main content

API Key Management

List, create, rotate, and revoke the rail_* API keys on your account. Key management lives on the Reporting API (https://api.tensorrail.com) under /v1/api-keys.

Reads are programmatic; mutations are dashboard actions

Listing keys and scopes works with any authenticated call. Creating, rotating, and revoking keys requires a signed-in dashboard operator with a fresh two-factor verification — an API key calling these endpoints receives 401 ERR_1019 (two_factor_required). This is deliberate: a leaked key must never be able to mint or replace credentials on its own.

Key modes​

Keys have the shape rail_<type>_<mode>_<secret> (see Authentication). The mode is chosen at creation:

ModePrefixOperates on
testrail_<type>_test_…Sandbox data
liverail_<type>_live_…Production data

List keys​

GET /v1/api-keys

curl "https://api.tensorrail.com/v1/api-keys" \
  -H "Authorization: Bearer rail_full_live_xxx"

Returns an array of key entries. Each entry includes at least:

FieldDescription
key_idThe key's identifier — used in the rotate / revoke paths
nameThe label given at creation
prefixThe non-secret prefix (e.g. rail_full_test_…); the secret itself is never returned after creation
createdCreation timestamp (RFC 3339)

List available scopes​

GET /v1/scopes — no authentication required.

curl "https://api.tensorrail.com/v1/scopes"
{ "scopes": ["payments:read", "payments:write", "refunds:read", "…"] }

This is the machine-readable form of the scope table. New keys carry the 19 default scopes; contact your account manager for additional scopes (for example routing:write).

Create a key​

POST /v1/api-keys — dashboard operator session + two-factor; scope api_keys:manage.

Body

FieldTypeRequiredDescription
modestringNotest (default) or live
namestringNoA label for the key

The new key's plaintext is returned once in the response — store it immediately; only the prefix is retrievable afterwards.

In the dashboard: Developers → API Keys → Create key.

Rotate a key​

POST /v1/api-keys/{id}/rotate — dashboard operator session + two-factor; scope api_keys:manage.

Rotation issues a replacement key and returns its plaintext once; the response's key_id identifies the new key. Rotation is the routine-hygiene path — the old key keeps working for a 24-hour grace window so you can deploy the replacement without downtime. Rotation requires a fresh two-factor step-up and is rate-limited. A security email is sent to your operators on every rotation.

For a suspected compromise, use Emergency key revoke instead: it kills the old key immediately, with no grace window and no cooldown.

Revoke a key​

DELETE /v1/api-keys/{id} — dashboard operator session + two-factor; scope api_keys:manage.

Revokes the key. In the dashboard: Developers → API Keys → Revoke.

Managed dashboard credentials

Key entries named tensorrail_gateway are TensorRail-managed credentials that keep your dashboard connected. They are hidden from the list and cannot be rotated or revoked through these endpoints (attempts return 403).

Errors​

CodeHTTPCause
ERR_1019401Mutation attempted without a fresh two-factor verification (including any API-key call)
ERR_1004403The session/key lacks api_keys:manage
ERR_2002400Malformed key id in the path
ERR_3010422Account provisioning is not complete yet
ERR_5005503The key service is temporarily unavailable; retry