---
title: "Import API Key"
method: POST
path: "/v2alpha1/admin/importedApiKeys"
tags: ["ApiKeys"]
---

# Import API Key

`POST /v2alpha1/admin/importedApiKeys`

Imports an external API key into the system. Allows importing keys from
legacy systems or external providers. The raw key is hashed (SHA-512/256
over network_id + 0x00 + raw key) and stored; the original key is never
retained. Imported keys support token derivation (JWT/Macaroon) like
issued keys.

```http
POST /v2alpha1/admin/importedApiKeys
{
  "raw_key": "sk_live_abc123xyz",
  "name": "Imported Stripe Key",
  "actor_id": "user_123"
}
```

## Request body

- ImportApiKeyRequest — ImportApiKeyRequest imports an external API key. The raw key is hashed with SHA-512/256 (over network_id + 0x00 + raw key) and only the hash is stored. Example: { "raw_key": "sk_live_abc123xyz789", "name": "Stripe Production Key", "actor_id": "payment-processor", "scopes": ["read", "write"], "ttl": "8760h", // 1 year (also accepts: 31536000s) "metadata": {"source": "stripe", "environment": "production"} }
  - `actor_id` string — actor_id is the identifier of the entity that owns this imported key. Required so every imported key is traceable to an actor for revocation and audit queries.
  - `ip_restriction` IPRestriction — IPRestriction defines IP-based access controls for an API key. When allowed_cidrs is non-empty, only requests from IPs matching at least one CIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed). Derived tokens (JWT/macaroon) inherit the parent key's CIDR allowlist: the restriction is sealed into the token at derivation and re-enforced on every verification.
    - `allowed_cidrs` string[] — allowed_cidrs is a list of CIDR ranges that are allowed to use this key. Supports both IPv4 (e.g., "10.0.0.0/8") and IPv6 (e.g., "2001:db8::/32"). If empty, all IPs are allowed (no restriction).
  - `metadata` object — metadata is a free-form JSON object for caller-defined attributes (e.g., source, environment, tags). Values may be strings, numbers, booleans, arrays, objects, or null. Total serialized size is capped at 4KB. AIP-148 metadata field.
  - `name` string
  - `rate_limit_policy` RateLimitPolicy — RateLimitPolicy describes the rate limit policy for an API key. In OSS mode, this policy is informational and meant to be consumed by upstream gateways (Envoy, Cloudflare, etc.) for enforcement. In commercial mode, Talos enforces rate limits using in-memory or Redis backends, both using the GCRA (Generic Cell Rate Algorithm). Compliant with draft-ietf-httpapi-ratelimit-headers-10.
    - `quota` string, int64 — quota is the number of requests allowed per window.
    - `unit` string
    - `window` string — window is the time window for the quota. Common values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).
  - `raw_key` string
  - `request_id` string
  - `scopes` string[]
  - `ttl` string — ttl sets the expiry as a duration from now. Encoded as a google.protobuf.Duration (string ending in "s", e.g. "3600s"). Accepted bounds: 1s to 315360000s (~10 years). If unset or zero, the project default TTL applies. For convenience, the server also accepts Go-style duration strings ("24h", "30m", "1h30m") and an extended unit set ("1d", "1w", "1mo", "1y"; approximations: 1mo = 30d, 1y = 365d). Clients should prefer the standard Duration encoding for portability.
  - `visibility` 'KEY_VISIBILITY_UNSPECIFIED' | 'KEY_VISIBILITY_SECRET' | 'KEY_VISIBILITY_PUBLIC' — KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys. Public keys use a different configurable prefix for visual distinction. Both types share the same scope/permission system — visibility is about exposure safety. - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET

## Response `200`

A successful response.

- ImportedApiKey — ImportedApiKey represents an API key imported from an external system. The raw key is hashed (SHA-512/256) and stored. The original key is never retained.
  - `actor_id` string
  - `create_time` string, date-time
  - `expire_time` string, date-time
  - `ip_restriction` IPRestriction — IPRestriction defines IP-based access controls for an API key. When allowed_cidrs is non-empty, only requests from IPs matching at least one CIDR range are permitted. Empty allowed_cidrs means no IP restriction (all IPs allowed). Derived tokens (JWT/macaroon) inherit the parent key's CIDR allowlist: the restriction is sealed into the token at derivation and re-enforced on every verification.
    - `allowed_cidrs` string[] — allowed_cidrs is a list of CIDR ranges that are allowed to use this key. Supports both IPv4 (e.g., "10.0.0.0/8") and IPv6 (e.g., "2001:db8::/32"). If empty, all IPs are allowed (no restriction).
  - `key_id` string
  - `last_used_time` string, date-time
  - `metadata` object — metadata is a free-form JSON object for caller-defined attributes (e.g., source, environment, tags). Values may be strings, numbers, booleans, arrays, objects, or null. Total serialized size is capped at 4KB. AIP-148 metadata field.
  - `name` string
  - `rate_limit_policy` RateLimitPolicy — RateLimitPolicy describes the rate limit policy for an API key. In OSS mode, this policy is informational and meant to be consumed by upstream gateways (Envoy, Cloudflare, etc.) for enforcement. In commercial mode, Talos enforces rate limits using in-memory or Redis backends, both using the GCRA (Generic Cell Rate Algorithm). Compliant with draft-ietf-httpapi-ratelimit-headers-10.
    - `quota` string, int64 — quota is the number of requests allowed per window.
    - `unit` string
    - `window` string — window is the time window for the quota. Common values: 60s (1 minute), 3600s (1 hour), 86400s (1 day).
  - `revocation_description` string — revocation_description provides free-form context for a revocation. Only set when revocation_reason is PRIVILEGE_WITHDRAWN. JSON API change: field was formerly revocation_reason_text. Field number 13 is unchanged so the change is wire-compatible for binary proto encoding.
  - `revocation_reason` 'REVOCATION_REASON_UNSPECIFIED' | 'REVOCATION_REASON_KEY_COMPROMISE' | 'REVOCATION_REASON_AFFILIATION_CHANGED' | 'REVOCATION_REASON_SUPERSEDED' | 'REVOCATION_REASON_PRIVILEGE_WITHDRAWN' — RevocationReason provides structured revocation reasons inspired by RFC 5280. Used in both admin and self-revocation flows. - REVOCATION_REASON_UNSPECIFIED: Default zero value. Use a specific reason; UNSPECIFIED is rejected by admin and self-revocation endpoints. - REVOCATION_REASON_KEY_COMPROMISE: The key was leaked or believed to be in the hands of an unauthorized party. - REVOCATION_REASON_AFFILIATION_CHANGED: The owning actor's relationship with the issuer changed (e.g., role change, departure). - REVOCATION_REASON_SUPERSEDED: A new key has replaced this one as part of a rotation. - REVOCATION_REASON_PRIVILEGE_WITHDRAWN: Admin-only. The actor's privilege to use this key was withdrawn by an operator. Self-revocation requests using this reason are rejected with InvalidArgument. Pair with `description` on the admin revoke requests to record the operator-supplied justification.
  - `scopes` string[]
  - `status` 'KEY_STATUS_UNSPECIFIED' | 'KEY_STATUS_ACTIVE' | 'KEY_STATUS_REVOKED' | 'KEY_STATUS_EXPIRED' — KeyStatus represents the lifecycle state of an API key. - KEY_STATUS_UNSPECIFIED: Default zero value. Never returned by the server. Treated as ACTIVE for backward compatibility but should not be relied on. - KEY_STATUS_ACTIVE: The key is valid and can be used to authenticate. - KEY_STATUS_REVOKED: The key was revoked. Verification fails with VERIFICATION_ERROR_REVOKED. See revocation_reason for the cause. - KEY_STATUS_EXPIRED: The key passed its expire_time. Verification fails with VERIFICATION_ERROR_EXPIRED. The transition is computed at read time and not persisted.
  - `update_time` string, date-time
  - `visibility` 'KEY_VISIBILITY_UNSPECIFIED' | 'KEY_VISIBILITY_SECRET' | 'KEY_VISIBILITY_PUBLIC' — KeyVisibility distinguishes public (client-safe) keys from secret (server-only) keys. Public keys use a different configurable prefix for visual distinction. Both types share the same scope/permission system — visibility is about exposure safety. - KEY_VISIBILITY_UNSPECIFIED: Treated as SECRET

## Other responses

- `201` — API key imported successfully.
- `default` — An unexpected error response.

---

[API](https://skmtc.net/ory/apis/ory-talos-api.md) · [All operations](https://skmtc.net/ory/apis/ory-talos-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ory/ory-talos-api/versions/faeb5ce56780/schema)