Batch operations

Talos batch endpoints verify or import many credentials in one request and return a result for each item. One bad item does not fail the rest of the batch.

Issue two keys to use in the batch operations:

CLI

export KEY1=$(talos keys issue "batch-key-1" \
  --actor user_1 --scopes "read" \
  --format json \
  -e "$TALOS_URL" 2>/dev/null | jq -er '.secret')

export KEY2=$(talos keys issue "batch-key-2" \
  --actor user_2 --scopes "write" \
  --format json \
  -e "$TALOS_URL" 2>/dev/null | jq -er '.secret')

echo "Keys issued"

curl

export KEY1=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
  -H "Content-Type: application/json" \
  -d '{"name":"batch-key-1","actor_id":"user_1","scopes":["read"]}' | \
  jq -er '.secret')

export KEY2=$(curl -s -X POST "$TALOS_URL/v2alpha1/admin/issuedApiKeys" \
  -H "Content-Type: application/json" \
  -d '{"name":"batch-key-2","actor_id":"user_2","scopes":["write"]}' | \
  jq -er '.secret')

echo "Keys issued"

Batch verify

Verify up to 100 credentials in a single request:

CLI

talos keys batch-verify "$KEY1" "$KEY2" "invalid-key-for-testing" \
  --format json \
  -e "$TALOS_URL" | jq .

curl

curl -s -X POST "$TALOS_URL/v2alpha1/admin/apiKeys:batchVerify" \
  -H "Content-Type: application/json" \
  -d "{
    \"requests\": [
      {\"credential\": \"$KEY1\"},
      {\"credential\": \"$KEY2\"},
      {\"credential\": \"invalid-key-for-testing\"}
    ]
  }" | jq .

Response format

The response contains a results array. Each element has the same fields as a single verify response. Talos returns results in the same order as the requests.

Invalid credentials return is_valid: false with an error_code — they do not cause the batch request to fail.

Missing HMAC configuration fails the whole batch with HTTP 500 when Talos needs to authenticate an issued API key. Batches containing only imported keys or stored keys rejected by expected_audiences do not require HMAC configuration.

Limits

Constraint	Value
Maximum credentials per request	100
Minimum credentials per request	1

Batch import

Import up to 1000 keys in a single request:

CLI

talos keys imported batch-import --file - -e "$TALOS_URL" <<'JSON'
[
  {"raw_key": "legacy_key_aaa", "name": "Legacy Key A", "actor_id": "migration"},
  {"raw_key": "legacy_key_bbb", "name": "Legacy Key B", "actor_id": "migration"},
  {"raw_key": "legacy_key_ccc", "name": "Legacy Key C", "actor_id": "migration", "scopes": ["read"]}
]
JSON

curl

curl -s -X POST "$TALOS_URL/v2alpha1/admin/importedApiKeys:batchCreate" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"raw_key": "legacy_key_aaa", "name": "Legacy Key A", "actor_id": "migration"},
      {"raw_key": "legacy_key_bbb", "name": "Legacy Key B", "actor_id": "migration"},
      {"raw_key": "legacy_key_ccc", "name": "Legacy Key C", "actor_id": "migration", "scopes": ["read"]}
    ]
  }' | jq .

Response format

The response includes a results array with per-item outcomes, plus success_count and failure_count counters. The response is 200 OK when at least one key succeeds. If every key fails, the endpoint returns a non-200 error instead. Check failure_count and the per-item error_code fields to detect partial failures.

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

Limits

Constraint	Value
Maximum keys per request	1000
Minimum keys per request	1

Next steps

• Import keys — single key import with full field reference
• Issue and verify — create and verify individual keys