Issue an API key

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.

Issue API keys with Ory Talos Secure API Keys in the Ory Console or with the API. Each key belongs to an actor, such as a user or a service, and carries the scopes that your API checks.

Before you begin

• To manage keys in the Ory Console, you need the Owner or Developer role in the project. Members with the Viewer role can't view keys or send requests from the Playground.
• If an API key page in the Ory Console shows Enable Ory Talos, select Enable API keys. The change takes a short time to apply. See Eventual consistency.

To call the API, you need your project slug and a project API key.

A project API key is required for all administrative operations. To create one, read Creating API Keys.

The quickstart shows where to find the project slug and how to set up the TypeScript and Go SDKs. The examples on this page read both values from environment variables:

export PROJECT_SLUG=<your-project-slug>
export ORY_API_KEY=<your-project-api-key>

Issue a key

Ory Console

1. Go to API Keys → Keys in the Ory Console and select Create API key.
2. On the Create API key page, fill in the fields:
   • Key name (required): a label that helps you recognize the key, up to 255 characters.
   • Actor (required): the ID of the user, service, or organization that owns the key, for example user:alice. Verification returns this value as actor_id, so your API knows who is calling. You also use it to find all keys of one owner.
   • Expiration: how long the key stays valid. See Choose an expiry.
   • Key type: Secret key or Public key. See Public keys.
3. Optionally, fill in the fields under Advanced settings:
   • Scopes: a comma-separated list of up to 100 permission scopes, for example read:data, write:data. Verification returns the scopes, and your API decides what each scope allows.
   • Rate limit (requests) and Per window: an optional limit for this key. See Per-key rate limits.
   • IP restrictions: a comma-separated list of CIDR ranges that the key works from, for example 10.0.0.0/8. Leave it empty to allow all IP addresses.
   • Metadata: a JSON object of up to 64 KB with your own attributes, for example {"env": "prod"}. Verification returns it too.
4. Select Create API key.
5. Copy the secret from the Your new API key secret dialog and store it in a safe place. Then select Done, I've copied my key.

curl

Send POST /v2alpha1/admin/issuedApiKeys. The fields name and actor_id are required.

curl -sS -X POST "https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/admin/issuedApiKeys" \
  -H "Authorization: Bearer $ORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing service",
    "actor_id": "user:alice",
    "scopes": ["read:data", "write:data"],
    "metadata": {"env": "prod"},
    "ttl": "720h"
  }' | jq

TypeScript

Call adminIssueApiKey. The fields name and actor_id are required.

import { ApiKeysApi, Configuration } from "@ory/client"

const apiKeys = new ApiKeysApi(
  new Configuration({
    basePath: `https://${process.env.PROJECT_SLUG}.projects.oryapis.com`,
    accessToken: process.env.ORY_API_KEY,
  }),
)

const { data } = await apiKeys.adminIssueApiKey({
  issueApiKeyRequest: {
    name: "Billing service",
    actor_id: "user:alice",
    scopes: ["read:data", "write:data"],
    metadata: { env: "prod" },
    ttl: "720h",
  },
})

console.log("Issued key", data.issued_api_key?.key_id)
// Give data.secret to the key owner. The API never returns it again.

Go

Call AdminIssueApiKey. The fields Name and ActorId are required.

package main

import (
	"context"
	"fmt"
	"os"

	ory "github.com/ory/client-go"
)

func main() {
	cfg := ory.NewConfiguration()
	cfg.Servers = ory.ServerConfigurations{{URL: "https://" + os.Getenv("PROJECT_SLUG") + ".projects.oryapis.com"}}
	client := ory.NewAPIClient(cfg)
	ctx := context.WithValue(context.Background(), ory.ContextAccessToken, os.Getenv("ORY_API_KEY"))

	resp, _, err := client.ApiKeysAPI.AdminIssueApiKey(ctx).IssueApiKeyRequest(ory.IssueApiKeyRequest{
		Name:     ory.PtrString("Billing service"),
		ActorId:  ory.PtrString("user:alice"),
		Scopes:   []string{"read:data", "write:data"},
		Metadata: map[string]interface{}{"env": "prod"},
		Ttl:      ory.PtrString("720h"),
	}).Execute()
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}

	key := resp.GetIssuedApiKey()
	fmt.Println("Issued key", key.GetKeyId())
	// Give resp.GetSecret() to the key owner. The API never returns it again.
}

Ory Talos Secure API Keys returns the secret only once: in the Your new API key secret dialog, or in the secret field of the API response, which has HTTP status 201 and contains the key in issued_api_key. Store the secret right away.

Choose an expiry

Every key expires. There is no option for a key that never expires.

• In the Ory Console, the Expiration list offers 1 hour, 6 hours, 12 hours, 24 hours, 3 days, 7 days, 30 days, and 365 days. To set another lifetime, select Custom… and enter the number of hours. The list preselects the project's default key lifetime and hides the options that are longer than the project's maximum key lifetime. A custom value above that maximum is rejected.
• With the API, set ttl to a duration such as 720h (30 days). If you leave out ttl, the key gets the project's default lifetime. A ttl of zero or longer than the project's maximum key lifetime is rejected.

For new projects, the default key lifetime is 7 days and the maximum is 2 years. To check or change both values, go to the Lifespans section of API Keys → Configuration in the Ory Console.

Public keys

A public key is a key that you plan to expose, for example in code that runs in a browser or a mobile app. It carries the public key prefix instead of the regular key prefix, so you and your users can tell public keys and secret keys apart. A public key authenticates like any other key, so give it only scopes that are safe to expose.

To issue a public key, select Public key under Key type in the Ory Console, or set visibility to KEY_VISIBILITY_PUBLIC in the API. First, set Public key prefix under Key prefixes in API Keys → Configuration in the Ory Console. Until the prefix is set, issuing a public key fails.

Per-key rate limits

Rate limit (requests) and Per window set how many verifications the key can pass in a time window, for example 100 requests per 60s. Set both fields or neither.

Ory Talos Secure API Keys enforces per-key rate limits only on the Enterprise plan, and only when rate limiting is turned on for the project. Otherwise, the key stores the limit, but verification ignores it. When a key goes over its limit, verification returns is_valid: false with the error code VERIFICATION_ERROR_RATE_LIMITED.

You turn on rate limiting in API Keys → Configuration in the Ory Console.