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:

FieldOptionsNotes
Name1–64 charactersFor example github-actions-web. Shown in usage, logs and the audit log.
AccessFull 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.
Expires90 days (default), 30 days, 1 year, NeverCan'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 50Empty 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:

AI Prompt — wire the Ostra key into this project
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:

PolicyError 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

ColumnShows
NameThe key's name.
KeyA hint such as ostk_live_…a91F. The full key is never shown again.
AccessFull access or Read only.
Created byWho created it.
Last usedWhen 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.
ExpiresThe expiry date, or never.
StatusActive, 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:

  1. Create a new key with the same settings.
  2. Deploy it everywhere the old key is used.
  3. 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

ErrorCauseFix
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.

Was this page helpful?

On this page