Import existing keys

Talos can manage API keys that were created outside the system. Import lets you migrate from a legacy key management solution or centralize keys from multiple providers without rotating credentials. For large migrations, use the batchImport API to import up to 1000 keys in a single request.

How import works

When you import a key, Talos stores a cryptographic hash (HMAC-SHA256) of the raw key. The original key is never stored. Verification works by computing the same hash and looking it up in the database.

Imported keys support the same features as issued keys: scopes, metadata, expiration, token derivation (JWT/macaroon), and revocation.

Import a single key

CLI

RESPONSE=$(talos keys imported import "Stripe production key" \
  --raw-key "sk_live_test_51OxAM2Qly" \
  --actor payment-service \
  --scopes "payments:read,payments:write" \
  --ttl 8760h \
  --metadata '{"source": "stripe", "environment": "production"}' \
  --format json \
  -e "$TALOS_URL" 2>/dev/null)

echo "$RESPONSE" | jq .

export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.imported_api_key.key_id')

curl

RESPONSE=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys" \
  -H "Content-Type: application/json" \
  -d '{
    "raw_key": "sk_live_test_51OxAM2Qly",
    "name": "Stripe production key",
    "actor_id": "payment-service",
    "scopes": ["payments:read", "payments:write"],
    "ttl": "8760h",
    "metadata": {"source": "stripe", "environment": "production"}
  }')

echo "$RESPONSE" | jq .

export IMPORTED_KEY_ID=$(echo "$RESPONSE" | jq -er '.key_id')

Request fields

The key fields are raw_key (the actual API key string), name, actor_id, and optional scopes, ttl, and metadata. For the complete field reference, see the ImportAPIKey API reference.

The response returns an imported_api_key object. The raw_key is never returned after import.

Verify an imported key

Imported keys use the same verification endpoint as issued keys. The data plane automatically detects the credential type:

CLI

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

curl

curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:verify" \
  -H "Content-Type: application/json" \
  -d '{"credential":"sk_live_test_51OxAM2Qly"}' | jq .

Batch import

Import up to 1000 keys in a single request:

CLI

talos keys imported batch-import --file - -e "$TALOS_URL" <<'JSON'
[
  {"raw_key": "ghp_batch_key_001", "name": "GitHub PAT 1", "actor_id": "dev-team"},
  {"raw_key": "ghp_batch_key_002", "name": "GitHub PAT 2", "actor_id": "dev-team"}
]
JSON

curl

curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchImport" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"raw_key": "ghp_batch_key_001", "name": "GitHub PAT 1", "actor_id": "dev-team"},
      {"raw_key": "ghp_batch_key_002", "name": "GitHub PAT 2", "actor_id": "dev-team"}
    ]
  }' | jq .

Batch response

The response includes a results array with per-item outcomes (imported_api_key on success, error_code and error_message on failure), plus success_count and failure_count counters. If at least one key succeeds, the HTTP response is 200 OK.

For the complete response field reference, see the BatchImportAPIKeys API reference. For batch import error codes, see the error codes reference.

List imported keys

CLI

talos keys imported list -e "$TALOS_URL"

curl

curl -s "$TALOS_URL/v2alpha1/admin/importedApiKeys?actor_id=payment-service&page_size=10" | jq .

Revoke an imported key

Imported keys are revoked through the same unified endpoint as issued keys:

CLI

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

curl

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

Delete an imported key

For permanent removal (no audit trail), use the delete endpoint:

CLI

talos keys imported delete "$IMPORTED_KEY_ID" -e "$TALOS_URL"

curl

curl -s -X DELETE "$TALOS_URL/v2alpha1/admin/importedApiKeys/$IMPORTED_KEY_ID"
echo ""
echo "Imported key deleted"

caution

Delete is permanent and irreversible. Prefer revocation for audit trail.

Next steps

• Batch operations -- batch verify and batch import in detail
• Key lifecycle -- update, rotate, and revoke keys
• Derive tokens -- mint JWTs or macaroons from imported keys