New Ory Agent Security is now live! Claim your complimentary test drive. Get Started!

Skip to main content

Introduction to Ory Talos Secure API Keys for Ory Network

info

Ory Talos Secure API Keys on Ory Network is in preview. The HTTP API is versioned v2alpha1, and request and response shapes can change. Pin the version of the Ory SDK that you use.

Ory Talos Secure API Keys issues, verifies, rotates, and revokes the API keys that your users and services use to call your APIs, and derives short-lived JWTs and macaroons from those keys.

On Ory Network, Ory Talos Secure API Keys is available in every project, fully managed. You can manage keys in the Ory Console, with the HTTP API, or with the Ory SDK. Your backend makes one API call to check each key it receives.

What Ory runs for you​

  • An isolated set per project. Each Ory Network project has its own API keys, derived tokens, signing keys, and settings. A key or token from one project is not valid in another project.
  • Storage and service. Ory stores your API keys and runs the service that issues and verifies them. You don't run databases or servers.
  • Signing keys and secrets. Ory generates, stores, and rotates the JWT signing keys and the HMAC secret for your project, and never returns the private material. You start a rotation in API Keys → Configuration in the Ory Console.
  • Secrets shown once. Ory Talos Secure API Keys returns the secret of an API key only once, when you issue or rotate the key. Securely store it right away or hand it to your user.

How it fits together​

  1. Your user or service sends a request to your API with an API key, for example in a request header.
  2. Your backend sends the key to POST /v2alpha1/admin/apiKeys:verify and authenticates with a project API key.
  3. Ory Talos Secure API Keys returns is_valid, the actor_id you assigned to the key (for example a user ID), and the key's scopes. An invalid key still returns HTTP 200, with is_valid: false and an error_code such as VERIFICATION_ERROR_REVOKED. Your API decides what the actor and scopes allow.
  4. Optional: to call other services, your backend derives a short-lived JWT from the key with POST /v2alpha1/admin/apiKeys:derive, which also needs the project API key. Those services verify the JWT offline with your project's public signing keys. They fetch the keys from https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/derivedKeys/jwks.json, which needs no credential.
tip

A service that verifies a JWT offline accepts it until it expires, even after you revoke the parent API key. Derived tokens expire after 1 hour by default. Keep that lifetime short.

Where you work​

Ory Console​

  • Go to API Keys → Keys in the Ory Console to issue, view, edit, rotate, and revoke API keys.
  • Go to API Keys → Imported in the Ory Console to import API keys from another system, so your users keep the keys they already have.
  • Go to API Keys → Playground in the Ory Console to verify a key or derive a JWT or macaroon from it without writing code.
  • Go to API Keys → Configuration in the Ory Console to set key lifetimes, key prefixes, and derived-token defaults, and to rotate the JWT signing key and the HMAC secret. Per-key rate limiting and verification caching need the Enterprise plan.

New projects have API keys enabled. If an API Keys page shows Enable Ory Talos instead, select Enable API keys. This generates your project's signing keys and sets the default settings.

https://console.ory.com/projects/current/api-keys/native

API Keys page in the Ory Console with a list of issued API keys, their status, and expiry dates

HTTP API​

Send requests to your project URL, https://$PROJECT_SLUG.projects.oryapis.com. You find the slug in the Project slug field on Project settings → Overview in the Ory Console. Admin endpoints are under /v2alpha1/admin/ and need a project API key in the Authorization: Bearer header. Call the admin endpoints from your backend only. Two public endpoints don't need a project API key:

  • GET /v2alpha1/derivedKeys/jwks.json returns the public keys for derived JWTs. It needs no credential.
  • POST /v2alpha1/apiKeys:selfRevoke lets a key holder revoke their own key. The request body must contain the full API key in credential as proof of possession.

Ory SDK​

The Ory SDK, which covers all Ory Network APIs, includes these endpoints for TypeScript and Go: ApiKeysApi in @ory/client and @ory/client-fetch version 1.22.56 and later, and ApiKeysAPI in github.com/ory/client-go version v1.22.48 and later. The Python and Dart SDKs don't include them yet. The quickstart shows how to set up the TypeScript and Go SDKs.

To run Ory Talos Secure API Keys on your own infrastructure, read the self-hosted documentation.

Next steps​