Open source quickstart

Issue, verify, and revoke an API key with the Ory Talos open-source edition. This guide uses Docker Compose with a SQLite backend, so you need git and Docker installed. Examples use the Ory Talos CLI, with curl as an alternative.

To run the commercial (OEL) edition with Postgres, see the Commercial quickstart instead.

Start the server

Clone the repository to fetch the Docker Compose file, then start the stack:

git clone https://github.com/ory/talos.git
cd talos
docker compose -f docker-compose.oss.yaml up --build -d

This starts Ory Talos with SQLite and Jaeger for tracing (UI at http://localhost:16686). Migrations run automatically. Ory Talos has no built-in web UI; manage keys with the API or CLI. For a web console, see Editions.

The server listens on http://localhost:4420. Wait for it to become healthy:

for i in $(seq 1 30); do
  if curl -sf http://localhost:4420/health/alive > /dev/null 2>&1; then
    echo "Server is ready"
    break
  fi
  sleep 1
done

Check that it responds:

curl -sf "$TALOS_URL/health/alive" | head -c 200

Issue an API key

Create an API key through the admin surface:

CLI

RESPONSE=$(talos keys issue "My first key" \
  --actor quickstart-user \
  --scopes "read:*,write:*" \
  --ttl 168h \
  --format json \
  -e "$TALOS_URL" 2>/dev/null)

echo "$RESPONSE" | jq .

export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')

curl

# Issue a key and capture the response
RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first key",
    "actor_id": "quickstart-user",
    "scopes": ["read:*", "write:*"],
    "ttl": "168h"
  }')

echo "$RESPONSE" | jq .

# Save the secret and key ID for later steps
export API_SECRET=$(echo "$RESPONSE" | jq -er '.secret')
export KEY_ID=$(echo "$RESPONSE" | jq -er '.issued_api_key.key_id')

The response contains two parts:

• issued_api_key — the key metadata (key_id, name, actor, scopes, expiration).
• secret — the full API key credential. It is shown once. Store it securely.

Verify the key

Send the secret to the verify endpoint to check that the key is active:

CLI

talos keys verify "$API_SECRET" -e "$TALOS_URL"

curl

VERIFY_RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
  -H "Content-Type: application/json" \
  -d "{\"credential\":\"$API_SECRET\"}")

echo "$VERIFY_RESPONSE" | jq .

The response sets is_valid to true and returns the key's metadata (actor, scopes, expiration).

Revoke the key

Revoke the key through the admin surface, using its ID:

CLI

talos keys revoke "$KEY_ID" --reason superseded -e "$TALOS_URL"

curl

curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys/${KEY_ID}:revoke" \
  -H "Content-Type: application/json" \
  -d '{"reason":"REVOCATION_REASON_SUPERSEDED"}'
echo ""
echo "Key revoked"

Verify that the revoked key no longer passes. The --no-cache flag (and the Cache-Control: no-cache header in the curl example) forces a fresh database lookup, bypassing any verification cache:

CLI

talos keys verify "$API_SECRET" --no-cache -e "$TALOS_URL" || true
echo "Revocation confirmed"

curl

REVOKE_CHECK=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -d "{\"credential\":\"$API_SECRET\"}")

echo "$REVOKE_CHECK" | jq .

# Verify the key is no longer active
if echo "$REVOKE_CHECK" | jq -e '.is_valid == false' > /dev/null 2>&1; then
  echo "Revocation confirmed"
else
  echo "ERROR: Key should have been revoked"
  exit 1
fi

The secret is still cryptographically valid, but verification now fails because the server checks revocation status on a fresh database lookup. When a verification cache is enabled, a revoked key can still pass until its cached entry expires, which is why this step bypasses the cache.

Stop the server

docker compose -f docker-compose.oss.yaml down

To also remove all data volumes:

docker compose -f docker-compose.oss.yaml down -v

Next steps

• Integration guide — detailed API walkthrough for all credential operations
• Operations guide — install, configure, and deploy Ory Talos in production
• Architecture — how the admin and self-service surfaces work