Getting an API key

In short

Your systems prove who they are with an API key: a long secret string sent with every request. A key belongs to one workspace and can only do what its scopes allow. To send data you need a key with the ingest:write scope.

Scope	Lets the key
`ingest:write`	Send customers, accounts, transactions, account events and FX rates, and send feedback on outcomes
`decide`	Ask for real-time fraud decisions and send feedback on them. See Calling the decision API

A key with only ingest:write can’t read anything back, can’t ask for decisions and can’t change settings. If it leaks, the damage is limited to sending data into your workspace.

Who can create keys

Only users with the API keys: manage permission, which the built-in Administrator role holds. If you’re the integration engineer, ask your SpeculaPro administrator to create the key and hand it to you through your secret manager. Don’t let anyone send it by email or chat.

How to create a key

The quickest way is the API keys tab in Settings: see Managing API keys.

Use the API instead when you want the key to expire on a set date (the screen creates keys without an expiry), or when you script key creation. The steps below use curl; any HTTP client works.

Sign in and keep the session cookie. Use your workspace slug, email, password and the current code from your authenticator app:
Terminal window
```
curl -c cookies.txt https://speculapro.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"workspace": "acme-pay", "email": "[email protected]",
       "password": "…", "totp_code": "482913"}'
```
The cookie file now holds your session. If the response is 401 with totp_required, the code was missing. If it is temporary_password_expired, your temporary password is more than 72 hours old: ask an administrator to issue a new one. invalid_credentials covers every other sign-in failure.
Create the key, naming the system and environment it is for. Add an expiry date: a year is a sensible maximum.
Terminal window
```
curl -b cookies.txt https://speculapro.example.com/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -H "Origin: https://speculapro.example.com" \
  -d '{"name": "MoMo platform – production",
       "scopes": ["ingest:write"],
       "expires_at": "2027-10-01T00:00:00Z"}'
```
The Origin header is required on every signed-in request that changes something (POST, PUT, PATCH, DELETE): it must be the address you reach SpeculaPro on. Browsers add it by themselves; curl does not, and without it the answer is 403. Requests made with an API key never need it.

Copy the key from the response into your secret manager straight away. It is in the key field and starts with spk_:

{
  "id": "0199c8e0-6b2f-7a51-8c44-2d9e7f13a0b6",
  "name": "MoMo platform – production",
  "prefix": "k3x9q2m7w4ab",
  "scopes": ["ingest:write"],
  "created_at": "2026-10-09T07:58:12Z",
  "expires_at": "2027-10-01T00:00:00Z",
  "key": "spk_k3x9q2m7w4ab_Vn2…Q8"
}

Sign out and delete the cookie file:

curl -b cookies.txt -X POST -H "Origin: https://speculapro.example.com" https://speculapro.example.com/api/v1/auth/logout
rm cookies.txt

How to use the key

Send it in the Authorization header of every request, after the word Bearer and a space:

curl https://speculapro.example.com/api/v1/ingest/fx-rates \
  -H "Authorization: Bearer $SPECULAPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"quote": "USD", "as_of": "2026-10-09", "rate": "15.25"}]}'

Response	Meaning
`401 unsupported authorization scheme`	The header doesn’t start with `Bearer`
`401 invalid api key`	Wrong, revoked or expired key
`401 api key required`	No key sent, or you called an ingest endpoint with a browser session instead of a key
`403 api key lacks scope ingest:write`	The key exists but wasn’t given `ingest:write`

How to keep keys safe

One key per system and per environment. “MoMo platform – production” and “MoMo platform – staging” are two keys. If one leaks, you revoke only that one.
Secret manager only. Never in source code, a shared drive, a ticket or a chat message.
HTTPS only. Never send a key over plain http://.
Set an expiry and put the renewal date in a calendar.

How to rotate a key without downtime

Create a new key with the same scopes and a new expiry.
Deploy the new key to your sending system and confirm requests succeed.

Revoke the old key (as a signed-in administrator):

curl -b cookies.txt -X DELETE -H "Origin: https://speculapro.example.com" https://speculapro.example.com/api/v1/api-keys/0199c8e0-6b2f-7a51-8c44-2d9e7f13a0b6

204 means revoked. 404 means the key doesn’t exist or was already revoked.

To see the workspace’s keys (names, prefixes, scopes, last use, expiry; never the secrets), call GET /api/v1/api-keys while signed in.