Obtain and manage a key

The API authenticates by key only. There is no endpoint that exchanges an email and a password for one: a password opens the web panel too, and would carry far more than an integration needs.

A key is always scoped to one organization, even for an account that belongs to several. It is sent in the Authorization header:

Authorization: Bearer 42|pQ7d…

Where a key comes from

The client creates it in their panel — Organization → API tokens — where it is shown once, then sends it to you. Rikochey keeps only a one-way hash of it: nobody, the client and Rikochey included, can read it back. A key that is lost is replaced, never recovered.

Store it as you store any other secret of your application: in configuration outside the document root, never in a page, never in version control.

Once you hold one key, POST /api/tokens mints further keys for the same organization — one per integration, so that revoking one never takes down the others.

Who can hold a token

A token opens the data of the whole organization: only its owners and administrators can obtain one, from the panel as from this API. A token stays valid only as long as its bearer keeps that role in an active organization:

• when the bearer is removed from the organization, or demoted to member, their tokens for that organization are revoked at once;
• whatever happens, every call checks the bearer's role again: a token whose bearer no longer has access receives 403 ("The holder of this token no longer has access to this organization.").

Plan for it: an integration built on a colleague's token stops the day they leave. Prefer a token held by a lasting owner of the organization.

Managing keys with a key

The four endpoints below act on the organization of the key that makes the call, and on the bearer's own keys only. A key never creates, lists or revokes keys of another organization, even one its bearer also belongs to: for that, start from a key of that organization, created in its panel.

All four answer 403 with "API tokens are reserved to owners and administrators of an active organization." when the calling token's bearer is no longer owner or admin.

GET /api/tokens

Lists the bearer's tokens for the calling token's organization.

Response 200

{
    "data": [{
        "id": 42,
        "name": "CRM integration",
        "team_id": 7,
        "abilities": ["team:read", "team:submit"],
        "created_at": "2026-09-14T08:12:00.000000Z",
        "last_used_at": "2026-09-16T07:40:11.000000Z",
        "expires_at": null
    }]
}

The token value is not included: it is only shown once, at creation.

POST /api/tokens

Creates a token for the calling token's organization.

Body

Response 201

{ "token": "43|Kd9f…", "team": { "id": 7, "slug": "portails-fermetures" } }

Errors

DELETE /api/tokens/{id}

Revokes one of the bearer's tokens for the calling token's organization. Takes effect immediately.

Response 200 — {"message": "Token revoked."}

Error 404 — {"message": "Token not found."} if the identifier is not one of those tokens.

DELETE /api/tokens

Revokes all the bearer's tokens for the calling token's organization, including the one used for the call. Tokens of the bearer's other organizations are kept.

Response 200 — {"message": "All tokens of this organization have been revoked."}

This call saws off the branch it sits on: the token that made it is revoked along with the others. Integrations using it lose access immediately.

Lifetime

A token created from the panel can carry an expiration date; without one, it never expires. An expired token is rejected like an unknown token. A token also ends when its bearer leaves the organization or becomes a plain member (see above).