Skip to main content

API Key Management

List the rail_* API keys on your account over the API; create, rotate, and revoke them in the dashboard, under Developers → API Keys. Listing lives on the Reporting API (https://api.tensorrail.com) under /v1/api-keys.

Reads are programmatic; mutations are dashboard-only

Listing keys and scopes works with any authenticated call. Creating, rotating, and revoking keys is done signed in to the dashboard, with a fresh two-factor verification, and is not reachable over the API at all: this is deliberate, so that a leaked key can never 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)
expirationnever, or the time the key stops working (RFC 3339). A key replaced by rotation carries the end of its 24-hour grace window here.

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​

In the dashboard: Developers → API Keys → Create API Key. Signed-in operator session, fresh two-factor. There is no API call for this: see the info box above.

You may hold two active secret keys per mode, so test and live are counted separately and two of each is the ceiling. A third is refused. The limit exists so a rotation has somewhere to land while the old key is still in use, and no further: spare keys nobody can account for are how a leaked key stays valid, because nobody knows what it was for. Revoke the one you have finished with, then create the next. The old key of a rotation still counts until its 24 hours end, so rotating while you hold two keys leaves three, and Create is refused until the old key stops working or you revoke it.

Choose test or live and, optionally, a name for the key. The new key's plaintext is shown once, in the dashboard; store it immediately, only the prefix is retrievable afterwards.

Rotate a key​

In the dashboard: Developers → API Keys → Rotate on the key's row. You confirm, enter a two-factor code, and the new key is shown once, with the time the old key stops working. There is no API call for this.

Rotation is the routine-hygiene path. It issues a replacement key with the same name, shown once. The old key keeps working for 24 hours, so you can deploy the replacement without downtime; after that it stops authenticating. The key list (GET /v1/api-keys) shows the old key's end time in expiration (and under the key in the dashboard). A security email is sent to your operators on every rotation, and rotating is rate-limited.

Cooldown: one rotation per hour. Rotating either key of a pair (the replacement, or the old key still in its grace window) again within one hour of the rotation that created the pair is refused, with the wait remaining shown. Rotating the old key again after the hour issues a third key and gives the old key a fresh 24 hours, leaving two replacements in use, so the dashboard does not offer Rotate on a key that is already being replaced: rotate its replacement instead.

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​

In the dashboard: Developers → API Keys → Revoke. Signed-in operator session, fresh two-factor. There is no API call for this.

Managed dashboard credentials

Some entries on your account are TensorRail-managed credentials that keep your dashboard connected. They are hidden from this list and the dashboard will not let you rotate or revoke one. You never need to manage them, and nothing you create here can collide with one.

Errors​

The codes below cover GET /v1/api-keys and GET /v1/scopes, the two calls on this page that are part of the API. Create, Rotate and Revoke are dashboard actions; the dashboard shows the same underlying conditions (two-factor needed, the two-keys-per-mode limit, the rotation cooldown) as plain messages rather than an API error code.

CodeHTTPCause
ERR_3010422Account provisioning is not complete yet
ERR_5005503The key service is temporarily unavailable; retry