API keys

Keys belong to your organisation, carry scopes, are shown once, and can only spend money up to a budget an Andromede administrator has granted.

An API key lets your own code do what you can do in the user portal: read your orders, place them, and download deliveries.

Keys belong to the organisation, not to you

A key is owned by your organisation, not by the person who created it. People change teams and leave; an integration built on a key tied to one person breaks when they do. Any owner or administrator of your organisation can see every key the organisation holds, and revoke any of them.

Create keys from the user portal. Creating one requires the owner or administrator role in your organisation.

The key is shown once

The full key is displayed exactly once, at the moment you create it. We store only a hash of it, so we genuinely cannot show it to you again — not through support, not on request.

Put it straight into your secret store. If you lose it, create a new key and revoke the old one; that is also the correct way to rotate a key on a schedule.

Lists of keys show a short prefix — the first eight characters — so you can tell which key is which without the key itself.

Scopes

A key carries a set of scopes. Grant the narrowest set that does the job.

Scope	What it allows
`orders:read`	List and read your organisation's orders.
`orders:write`	Place and accept orders. This scope spends money.
`artifacts:read`	Download deliveries.

orders:write is a financial instrument and is worth treating as one. A key that only reads data should never carry it.

Budgets

A budget is granted by an Andromede administrator, not by you. There is no control in the user portal that raises a key's budget, by design: the budget is the ceiling on what a key can commit your organisation to spending, and it is not something an integration should be able to raise on its own behalf.

Three consequences worth knowing:

A key with no budget granted cannot place orders at all. It can still read and download with the appropriate scopes. This is the default for a new key — no budget is granted automatically.
A request that would take the key past its budget is refused, with a 402 response that names the remaining budget. Nothing is half-placed.
Spending is counted when an order is accepted, not when it is drafted. Drafting and quoting cost nothing, so an integration can explore freely.

Ask your Andromede contact to grant or raise a budget. It is a quick conversation, and it is a deliberate one.

Revoking

Revocation takes effect immediately and cannot be undone. A revoked key stays listed, with the time it was revoked and who revoked it, so the record of what existed does not disappear along with the access.

Revoke a key the moment you suspect it has leaked. Then create a new one — that is the whole of key rotation here.

Using a key

The API is plain HTTP — there is no Andromede tool to install, and any client in any language will do. The key goes in a header:

curl -H "Authorization: Bearer $ANDROMEDE_API_KEY" \
     https://<your-api-host>/my/orgs/<org id>/orders

Never put a key in a URL, a query string, a client-side bundle or a repository. The Authorization header is the only supported place for it.

Getting your data lists the routes.

Availability. Keys, scopes and budgets are being released alongside the user portal. This page describes what they do; ask your Andromede contact if you need a key before then.