API Keys

A project API key is the simplest way to authenticate API calls from a CLI, SDK, or external system. Each key is scoped to one project. Keys do not carry OAuth scopes — they grant full project access. Use a Sentinel Pass when you need finer permissions or per-agent metrics.

1. Open API key management

1. Admin → Projects → {your project}.
2. Open the Keys & Access tab (the route uses api-access).
3. Switch to the API Keys sub-tab.

You see a list of existing keys with creation date, last-used timestamp, optional note, and optional expiry.

2. Create a key

1. Click Create API Key.
2. Enter a note describing what this key is for — e.g. "GitHub Actions deploy". The web creation wizard requires a non-empty note; do not assume every API endpoint applies the same validation.
3. If your management screen offers an expiry date, configure it there and check the returned key record. Only treat a key as expiring when its saved expiresAt is present; a blank saved expiry means no date-based expiry.
4. Click Create.
5. Copy the full secret immediately. The creation result shows it; the masked value in a list is not a usable replacement. If you lose access to the full secret, create a replacement, update consumers and revoke the old key.

3. Use a key

Send the key in the Authorization header on every request:

Authorization: Bearer <your-api-key>

The Traylinx CLI, Python SDK, and JavaScript SDK pick the key up automatically from an environment variable. See the SDK quickstart in the API reference for the exact variable name.

4. Rotate a key

There is no in-place rotation. To rotate: 1. Create a new key with the same note. 2. Update your deployment / CI / local env to use the new key. 3. Delete the old key.

Plan rotations during low-traffic windows; the old key works until you delete it.

5. Delete a key

1. Open the key's row.
2. Click Delete.
3. Confirm.

Deletion is immediate and irreversible. Any client still using the deleted key will get 401 Unauthorized on its next call.

6. What you can see

• Last used timestamp helps spot abandoned keys you can safely delete.
• The creation response exposes the full secret as meta.secretKey. Copy it immediately into your secret manager; do not rely on chat history or the masked list value to recover it.
• Traylinx maintains hashes for validation and encrypted secret material for authorized platform operations. It is inaccurate to say that only a hash is stored. If you cannot recover a usable secret through your authorized workflow, create a replacement and revoke the old key.

7. Best practices

• Note every key. A blank note becomes "what does this even do?" six months later.
• Set an expiry for keys handed to short-lived projects, contractors, or experiments.
• Use Sentinel Pass instead of API keys when an agent needs scoped permissions or per-call analytics.
• One key per consumer. Don't share a key between your CI and a developer's laptop — you'll never be able to rotate cleanly.

For OAuth-style credentials with scopes, see Sentinel Pass. For LLM provider keys (OpenAI, Anthropic, etc.) used inside projects, open the API Access → LLM Keys sub-tab in your project.

---

_{Mirrored from traylinx-web:docs/user-manuals/security/api_keys.md. Edit the source in the traylinx-web repo — changes here are overwritten by the sync script.}