Authentication

Every request to the Altuq API must carry a valid API key. Keys are created in the console and belong to a single project; usage is metered against that project.

The Authorization header

Send the key as a bearer token in the Authorization header on every request:

Authorization: Bearer ak_1a2b3c4d_9f8e7d6c5b4a3210fedcba9876543210

curl "https://api.altuq.ai/v1/geocoding/forward?query=Tokyo%20Station" \
  -H "Authorization: Bearer ak_1a2b3c4d_9f8e7d6c5b4a3210fedcba9876543210"

This is an API key, not a console login/session token — the two are different credentials and are not interchangeable.

Key format

An Altuq API key has three parts joined by underscores:

ak_<key-id>_<secret>

• ak_ — a fixed prefix identifying an Altuq API key.
• <key-id> — the public identifier for the key (hex). It is safe to log and appears in the console so you can tell keys apart.
• <secret> — the secret material (hex). Treat it like a password.

The full key is shown once, at creation time, and is never recoverable afterward. The platform stores only a hash of the secret, so no one — including Altuq — can reproduce a key from storage. If a key is lost or exposed, revoke it in the console and issue a new one.

warning

Never embed a key in client-side code, a public repository, or a URL. Keep keys server-side and rotate them if you suspect exposure.

Rejected keys

A missing, malformed, unknown, wrong-secret, or revoked key all return the same response — key existence is never revealed:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{ "error": { "code": "unauthorized", "message": "invalid or missing API key" } }

Because every rejection is identical, a 401 does not tell you why the key was refused. Check that:

1. the Authorization header is present and spelled Bearer <key>,
2. you copied the whole key including the ak_ prefix and both underscores,
3. the key has not been revoked in the console.

See Errors for the complete list of status codes.