API keys
Create, use, edit, rotate and revoke Ostra API keys in the TestRelic Console — access levels, expiry, monthly spend caps, IP allowlists, RPM overrides and workspace key policy.
An API key authenticates every Ostra request, over REST and MCP. Manage keys on API keys (console.testrelic.ai/keys). Owners, admins and developers can create, edit and revoke keys; everyone in the workspace can see the list.
Keys look like ostk_live_ followed by 40 letters and digits. A key isn't scoped to a model or task: one key works for Ostra Decision and Ostra Pro, over REST and MCP. Create separate keys for separate systems so you can revoke one without affecting the rest.
Create a key
Click Create key and fill in the dialog:
| Field | Options | Notes |
|---|---|---|
| Name | 1–64 characters | For example github-actions-web. Shown in usage, logs and the audit log. |
| Access | Full access ("All tasks · API and MCP") or Read only ("List models and MCP tools · can't run models") | Read-only keys can call GET /models, POST /warm, and MCP initialize, tools/list and ostra_list_models. |
| Expires | 90 days (default), 30 days, 1 year, Never | Can't be changed later. |
| Monthly spend cap (USD) | Empty for no cap, or an amount with at most two decimals (up to $1,000,000) | Resets each calendar month (UTC). |
| IP allowlist (optional) | Comma-separated IPv4/IPv6 addresses or CIDR ranges, up to 50 | Empty allows any address. |
Click Create. The Save your key dialog shows the full key: "This is the only time the full key is shown. Store it in your secrets manager — you can't view it again." Click Copy, then Done.
Store it as an environment variable or CI secret named OSTRA_API_KEY, which every sample in these docs reads:
Configure this project to use an Ostra API key safely.
1. Read the key only from the OSTRA_API_KEY environment variable. Never hard-code it.
2. Add OSTRA_API_KEY=placeholder to .env.example (not .env), and make sure .env is in .gitignore.
3. In our CI config, read OSTRA_API_KEY from the CI secret store (e.g. GitHub Actions: secrets.OSTRA_API_KEY) and expose it only to the steps that call Ostra.
4. Add a startup check that fails with a clear message if OSTRA_API_KEY is missing.
Ostra API base URL: https://ostra.testrelic.ai/api/v1 (auth: Authorization: Bearer $OSTRA_API_KEY).Send it as Authorization: Bearer <key> (Ostra Pro routes also accept x-api-key). See Authentication.
Workspace key policy
If an owner or admin set a key policy in Settings → Security and SSO, new keys must follow it:
| Policy | Error when a key breaks it |
|---|---|
| Maximum key lifetime: must expire within 30, 90 or 365 days | "This workspace requires keys to expire within N days." |
| Require an IP allowlist on full-access keys | "This workspace requires an IP allowlist on full-access keys." |
Quick-create buttons (Create a key for MCP on the MCP page, and the onboarding key) follow the policy for you: they use the longest lifetime it allows, and ask for an allowlist when one is required. In the Create key dialog, pick an expiry and allowlist that meet the policy; otherwise the key is refused with the message above.
The key list
| Column | Shows |
|---|---|
| Name | The key's name. |
| Key | A hint such as ostk_live_…a91F. The full key is never shown again. |
| Access | Full access or Read only. |
| Created by | Who created it. |
| Last used | When it last made a request (updated at most once a minute). |
| Requests (30d) | Requests in the last 30 days. |
| Spend cap | $X/mo, or none. |
| Expires | The expiry date, or never. |
| Status | Active, Expires in N d (7 days or fewer left), Expired or Revoked. |
Edit a key
⋯ → Edit changes the Name, Monthly spend cap, RPM override and IP allowlist. "Access and expiry can't be changed. Create a new key instead."
The RPM override (a whole number from 1 to 100,000) lowers the requests-per-minute limit for this key: "Lower of this and the workspace limit applies." It's compared against the whole workspace's requests that minute, so use it to stop one integration from using up the workspace's limit. See Rate limits.
Rotate a key
Keys can't be rotated in place. To rotate:
- Create a new key with the same settings.
- Deploy it everywhere the old key is used.
- Revoke the old key.
Revoke a key
⋯ → Revoke asks for confirmation: "Revoke <name>? … will fail immediately, over REST and MCP. This can't be undone." Afterwards: "Revoked <name>. Requests with it now fail with 401."
Revoked keys stay in the list for the record; keys can't be deleted. Removing a member doesn't revoke the keys they created.
When a key stops working
| Error | Cause | Fix |
|---|---|---|
401 "Invalid API key." | Typo, or the key belongs to another environment. | Copy the key again from your secrets store. |
401 "This API key has been revoked." / "…has expired." | Revoked or past its expiry. | Create a new key. |
403 "Requests from this IP address are not allowed for this API key." | Caller's IP isn't in the allowlist. | Add the address or range in Edit. |
403 "This API key is read-only and cannot run predictions." | Read-only key used to run a model. | Use a Full-access key. |
402 spend_limit_reached with scope: "key" | The key's monthly spend cap is reached. | Raise the cap in Edit, or wait for next month (UTC). |
More in Errors.
Workspaces & members
Create workspaces, choose their region, invite members, accept invitations, assign roles, transfer ownership, and see exactly what each role can do in the TestRelic Console.
Playground
Try Ostra Pro and Ostra Decision in the TestRelic Console — chat, presets, thinking, tools, attachments, Compare, history, model status, and copying the request as code.