API keys

In short

People sign in with a password and an authenticator app. Systems (your payment switch, your core banking extract job) can’t do that, so they use an API key, a long secret string that identifies your workspace and says what the system is allowed to do.

Treat an API key exactly like a password for your whole integration. Anyone holding it can send data into your workspace, or ask for decisions, as you.

What a key looks like

spk_k3x9q2m7w4ab_Vn2...long random secret...Q8
└┬┘ └─────┬────┘ └──────────────┬───────────┘
 │     prefix                 secret
 │  (shown in lists,     (shown only once,
 │   used for lookup)     never stored)
 └─ "SpeculaPro key"

Part	Purpose
spk_	Marks it as a SpeculaPro key, which helps secret scanners recognise a leaked key
Prefix	Identifies the key. Shown in the key list so you can tell keys apart; not secret on its own
Secret	The part that proves possession. SpeculaPro stores only its SHA-256 fingerprint

Systems send the full key with each request as a bearer token:

Authorization: Bearer spk_k3x9q2m7w4ab_Vn2...Q8

Keys in a multi-region service

Where SpeculaPro is hosted in more than one region, a key also carries its region between spk and the prefix: spk_gh_k3x9q2m7w4ab_…. A key sent to another region is refused with 421 and the address to use. Keys of a single installation, and keys created before regions, have no region part. See Regions for integrators.

Scopes: what a key may do

Each key carries one or more scopes. A key can do only what its scopes allow.

Scope	Allows	Give it to
ingest:write	Sending transactions, customers, accounts, account events and FX rates into your workspace, and sending feedback on outcomes	Your data feeds, and scheduled jobs that send batches through the ingest API. (Uploading a file under Settings → Data import uses an administrator’s own session, not a key)
decide	Asking for real-time decisions and sending feedback on them. It can’t read the decision log or anything else back	Your payment switch or authorisation service

One key per system, smallest scope

Create a separate key for each system, with only the scopes it needs. If the nightly batch job’s key leaks, you revoke that one key; payments carry on, because the payment switch has its own.

Creating a key

Creating, listing, rotating and revoking keys needs the api_keys.manage permission, which the Administrator role has. Administrators do this on the API keys tab of Settings: see Managing API keys.

When you create a key you give it:

• a name that says what uses it (for example Card switch – production),
• its scopes,
• optionally an expiry date, after which the key stops working. The API keys screen doesn’t offer one yet; to set an expiry, create the key through the API with expires_at, as shown in Getting an API key. The screen then shows the key’s expires date, and expired once it has passed.

You see the full key only once

The complete key is shown once, when it is created, and can’t be shown again: SpeculaPro doesn’t keep it. Copy it straight into your secret manager. If it’s lost, revoke it and create a new one.

Storing keys

• Do keep keys in a secret manager (Vault, AWS Secrets Manager, a Kubernetes secret, or similar) and inject them at runtime.
• Don’t put keys in source code, Git repositories, tickets, chat messages, emails or screenshots.
• Don’t share one key between test and production.

Revoking a key

Revoke a key as soon as you suspect it has leaked, or when the system that used it is retired. Revocation can’t be undone. On screen, select Revoke on the key’s row in Settings › API keys; see How to revoke a key.

Revocation takes effect within about 5 seconds

For speed, each SpeculaPro server briefly remembers keys it has recently checked. Revocation is immediate on the server that handled it, and reaches every other server within about 5 seconds. If you’re responding to a leak, allow for this window.

Rotating keys

Rotate keys regularly (for example yearly), and always when someone with access to them leaves. There are two ways.

In one step. Select Rotate on the key’s row (or call POST /api/v1/api-keys/{id}/rotate). SpeculaPro makes a new key with the same name, scopes and expiry date, returns it once, and stops the old key in the same transaction. Whoever rotates becomes the new key’s creator. The system is refused until it has the new key, so have its team ready. Rotation hands out a new secret, so it follows the same approval rule as creating a key; while a rotation waits for approval, the old key keeps working. An expired key can’t be rotated. See How to rotate a key.

Without downtime.

1. Create a new key with the same scopes.
2. Deploy it to the system alongside the old one, or switch the system over.
3. Confirm traffic is arriving with the new key.
4. Revoke the old key.

Setting an expiry date on every key makes sure forgotten keys don’t live forever.

When someone leaves

A key belongs to the workspace, not to a person: deactivating the person who created it doesn’t stop it. That person is also the only one who ever saw the secret. So SpeculaPro records who created each key, and acts when they are deactivated, by an administrator or by your identity provider over SCIM:

Workspace setting revoke_api_keys_on_deactivation	Effect on each working key the person created
Off (the default)	The key keeps working and is marked rotation due, with the person and the time, until someone rotates or revokes it
On	The key is revoked in the same transaction as the deactivation

In both cases the other people who hold api_keys.manage are notified, with the person’s name and a count, never a key. The choice is the workspace’s because each default has a cost: a key left working is a leaver’s standing access, and a key revoked automatically stops the system that uses it. Changing the setting is a Security settings change under the approval policy, in either direction.

What this does not cover:

• Only the creator is tracked. SpeculaPro can’t know who else was given a key, from a secret manager or a colleague. When anyone with access to a key leaves, rotate it yourself.
• Re-enabling the person doesn’t clear the mark. Only rotating or revoking does.

Self-hosted installations expose the number of working keys still due for rotation as the speculapro_api_keys_rotation_due metric, and the Helm chart’s SpeculaProAPIKeysRotationDue alert fires when any has waited a day. See Monitoring.

Audit

Creating, rotating and revoking keys, and marking a key rotation due, are recorded in the audit log (api_key.create, api_key.rotate, api_key.revoke, api_key.rotation_due), with who did it and when. Actions taken with a key are recorded against the key, so you can tell which integration did what.

Related

• Sessions
• Data ownership and ingestion
• A real-time decision, step by step
• Regions for integrators