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

Skip to main content

Import API keys

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.

Import the API keys that your customers already have from another system into Ory Talos Secure API Keys.

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>

Import existing keys​

If your customers already have API keys from another system, import those keys so that your customers can keep using their current secrets. Ory Talos Secure API Keys stores only a hash of each imported secret, and verifies imported keys the same way as issued keys.

  1. Go to API Keys → Imported in the Ory Console and select Import key.
  2. On the Import API key page, enter a Key name, the owner's Actor, and the existing secret in API key secret.
  3. Optionally, set the other fields. Expires after works like Expiration when you issue a key, and its calendar button sets an exact expiry date. Key type and Advanced settings work the same as when you issue a key.
  4. Select Import key.
https://console.ory.com/projects/current/api-keys/imported

Imported keys page in the Ory Console with a list of imported API keys

Imported keys follow these rules:

  • You can import a secret only once per project. Importing the same secret again fails.
  • A secret that has the format of an issued key or a derived token can't be imported.
  • Imported keys get an expiry the same way as issued keys, and the same project maximum applies.
  • You can't rotate an imported key. To replace one, issue a new key, move the client to it, and then revoke or delete the imported key.

Import keys in bulk​

To import many keys, send POST /v2alpha1/admin/importedApiKeys:batchCreate with up to 1,000 items in requests. The Ory Console doesn't offer bulk import. Each item has the same fields as a single import, and each item succeeds or fails on its own:

  • If at least one item succeeds, the response has HTTP status 200. results has one entry per item, in request order. Each entry has the index of the item and either the imported_api_key or an error_code and error_message. success_count and failure_count summarize the batch.
  • If every item fails, the whole request fails with an error status.
  • Items that would take the project over its active key limit fail with BATCH_CREATE_IMPORTED_API_KEYS_ERROR_RESOURCE_EXHAUSTED.

When you retry, send only the items that failed. Items that were already imported fail with BATCH_CREATE_IMPORTED_API_KEYS_ERROR_ALREADY_EXISTS.

curl -sS -X POST "https://$PROJECT_SLUG.projects.oryapis.com/v2alpha1/admin/importedApiKeys:batchCreate" \
  -H "Authorization: Bearer $ORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"raw_key": "legacy-key-EXAMPLE-1", "name": "Acme production", "actor_id": "org:acme"},
      {"raw_key": "legacy-key-EXAMPLE-2", "name": "Globex staging", "actor_id": "org:globex"}
    ]
  }' | jq

Delete an imported key​

Deleting an imported key removes it permanently. The key disappears from the list and can't be restored. To keep a record of the key, revoke it instead.

  1. Go to API Keys → Imported in the Ory Console, open the row menu of the key, and select Delete. On the key detail page, Delete key is in the Danger zone section.
  2. In the Delete API key? dialog, select Delete key.