Authentication

Every call carries a bearer token:

Authorization: Bearer <token>

Tokens are created from Profile → API tokens in the control panel. The plaintext is shown once, at issuance, and is never stored — only its SHA-256 digest and its last four characters are, so a lost token is replaced rather than recovered.

What a token can do

A token acts as the person who created it, with exactly their rights. What that means in practice:

A slug outside your organizations is a 404, never a 403 — an outsider cannot probe for which application names exist. A slug that two of your organizations both own is a 409 telling you to disambiguate with ?org=<slug>.

Who am I

GET /cli/me

Answers with the account and the label of the token that authenticated, which is what makes "revoke that one" actionable when a consumer holds several.

Two kinds of token

A credential can belong to a person or to an organization, and a machine consumer should hold the second.

An organization token is what a service that deploys on somebody's behalf should carry. It keeps working when whoever created it leaves the organization, revoking it touches nobody's account, and the deploys it makes are attributed to the organization rather than to a person who did not make them.

Creating one takes the owner or admin role. Both kinds arrive on the same header and are told apart by the platform, so nothing in the rest of this portal depends on which you hold.

What an organization token can do

Everything an owner can do operationally: create applications, deploy them, set variables, read where they answer. It cannot change billing or membership, or delete the organization — those live in the control panel, which a token cannot sign in to at all.

It is deliberately not least-privilege: there is no read-only variant yet. If you need a credential that can read addresses but not deploy, say so and it can be designed — what this one buys is attribution and lifecycle, not a narrower blast radius.

Which one am I holding?

GET /cli/me

{
    "kind": "organization",
    "organization": "acme",
    "username": null,
    "email": null,
    "displayName": "Acme",
    "tokenLabel": "deploy bot"
}

A person's token answers the other way round:

{
    "kind": "user",
    "organization": null,
    "username": "dev",
    "email": "dev@example.com",
    "displayName": "Dev",
    "tokenLabel": "laptop"
}

kind is what a client should branch on. The account behind an organization token is a machine the platform manages, so its username and address are withheld rather than offered for a client to display as though a person held the credential.