Authentication

Every request authenticates with a single API key sent in the X-API-Key header. The key identifies the store and carries the scopes that decide which endpoints it can reach.

The X-API-Key header

Send the key as the sole value of the X-API-Key header on every request:

curl --fail-with-body https://integrations.allomancy.net/v1/store \
  -H "X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"

import requests

response = requests.get(
    "https://integrations.allomancy.net/v1/store",
    headers={"X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w"},
)
print(response.json())

const response = await fetch("https://integrations.allomancy.net/v1/store", {
  headers: { "X-API-Key": "allo_live_8Kd2...zQ.Hk9...4w" },
});
console.log(await response.json());

<?php
$ch = curl_init("https://integrations.allomancy.net/v1/store");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: allo_live_8Kd2...zQ.Hk9...4w"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Send exactly one value. A request with no X-API-Key header, an empty value, or more than one value is rejected.

Key format

A live key has three parts: a fixed prefix, a Base64Url payload, and a Base64Url signature, with the payload and signature joined by a dot.

allo_live_<base64url-payload>.<base64url-signature>

In the dashboard, a key is shown by its preview rather than its full value. The preview keeps the prefix and the last six characters:

allo_live_***Hk94w

The full key is shown only once, at the moment it is created. Allomancy stores only a hash of the key, so the full value can never be retrieved later. Treat the key like a password: anyone who holds it can act on the store within the key's scopes.

The key lifecycle

The store owner manages keys in Allomancy Stores on the API Keys page.

• Create. Click "Create API Key" and give the key a name (3 to 128 characters, unique among the store's active keys), grant it one or more scopes, and optionally set a future expiry date. Leaving the expiry blank keeps the key active until it is revoked. The full key is displayed once on creation.
• Edit. Click "PencilLine icon button" on a key's row to change its name, scopes, or expiry date. A revoked key cannot be edited.
• Revoke. Click "Ban icon button" on a key's row to invalidate it immediately. Revocation cannot be undone, and any service using the key loses access at once. An optional reason can be recorded.

There is no separate rotate action in the dashboard. To rotate a key, create a new one and revoke the old one once the integration is using the replacement.

Status codes

Authentication and authorization surface through three status codes:

Rate limits

Two limits apply, both enforced server-side:

• Authenticated requests are limited per key, by default 60 requests per minute.
• Failed authentication attempts are limited per client IP address, by default 10 per minute. This throttles attempts to guess a key.

A 429 response means a limit was reached; back off and wait before retrying.

Rate-limit headers

Authenticated responses (both successful responses and a 429) carry your current quota:

An authenticated 429 additionally carries Retry-After, the number of seconds to wait before retrying. It is a conservative upper bound, the full window.

The unauthenticated 429 returned after too many failed key attempts carries only Retry-After. It does not include the RateLimit-* headers, because quota configuration is not disclosed to unauthenticated callers.

If the rate-limit backend is briefly unavailable, a request may be rejected with a 429 that carries RateLimit-Policy and Retry-After but omits the numeric RateLimit-Limit and RateLimit-Remaining. Treat missing quota numbers as unknown, not as unlimited.