Skip to content
Facteur

Type at least two characters.

Create an API key and wire up your test suite

Create a key, use it from CI, replace it without downtime and revoke it. What it reaches, and what it will never reach.

An API key lets your tests call the API with no browser and no session. It belongs to the organization, which means it survives the departure of whoever created it: your CI does not break because somebody changed jobs.

You have to be an owner or an administrator of the organization to create one.

Create a key

Open Settings → API keys → Create a key and fill in four fields.

  1. A name. It is what will tell you which one to revoke in six months: "GitHub CI", "Camille's staging".
  2. What it can do. In the workspaces: read, or read and write. On the organization: nothing, read, or read and write the workspaces, for a provisioning script. Read-only is enough for a test suite.
  3. Where. Tick the workspaces the key reaches, at least one, or choose all workspaces, the ones you create later included.
  4. A duration. 30, 90, 180 or 365 days. After that date the key stops working; you can replace it before.

The secret is shown once only, right after creation. We keep nothing but a hash of it: neither you nor we can retrieve it afterwards. Copy it straight into your CI's secrets.

Use it

One Authorization header, and that is all:

curl -H "Authorization: Bearer fk_your_key" \
  https://api.facteur.eu/inboxes

A key is passed as a Bearer only. There is no Basic scheme, and the API addresses carry no version prefix.

Allow 600 requests per minute per key. Past that, the response is 429 RATE_LIMITED, with a Retry-After header.

Every route, its permission and its refusals are in the API reference that the API publishes itself: https://api.facteur.eu/openapi.json in English and https://api.facteur.eu/openapi.fr.json in French. The documentation portal for developers is not online yet.

Choose the scope

A key answers two questions separately, which lets you hand out little at a time.

What it can do, in four scopes and two families:

Scope What it opens
ws:read Read the messages of the workspaces it targets
ws:write Create and delete inboxes there
org:read List the workspaces, and see who reaches each one
org:write Create one, rename it, tag it, and add or remove the colleagues who reach it

Where it can do it: all your workspaces, or only the ones you name.

Write implies read within a family, and nothing crosses families. org:write therefore gives no access to your mail: a script that provisions workspaces has no business reading the messages inside them.

If you choose "all workspaces", the scope also covers the ones you create later. A list frozen at creation would be a key that silently stops covering your new workspaces.

A key never goes beyond the person who creates it. The org: permissions and the "all workspaces" choice need the right to manage workspaces, and every workspace you tick must be one you reach yourself.

What a key never reaches

Whatever its scope.

What the key tries The refusal What you do
Create, replace or revoke a key No route Go through the application. A stolen key that replaces itself would make its own revocation meaningless
Touch your account: password, second factor, passkeys No route A leaked key does not take the account
Write while it is read-only 403 API_KEY_PERMISSION_MISSING The response names the missing permission (permission)
List workspaces without org:* 403 API_KEY_PERMISSION_MISSING Create a key with org:read
Bring somebody into the organization, pay, write an alert destination No route Invite from the application. See Members and seats
Delete a workspace 403 API_KEY_CANNOT_DELETE_WORKSPACE Delete from the application: no key, whatever its permission, has that right
Read the mail of a workspace outside its scope 404 A key targeting "staging" does not read the main workspace. Same boundary as members, see Workspaces

A support session cannot create a key either, even with your explicit consent: the key would afterwards be indistinguishable from one you had created yourself.

Replace without downtime

Replacing creates a fresh key and lets the old one live for 24 hours by default. The new one takes the permissions and the workspaces of the old one, lasts 90 days, and carries the old name followed by "(replaced" and today's date. Deploy the new secret, watch a green build go by, and the old one goes out on its own. A rotation that cuts is a rotation nobody performs.

An already revoked key cannot be replaced: that would keep it alive for a few more hours, which would undo the revocation (409 API_KEY_REVOKED). An expired key can be replaced.

Revoke

Immediate, with no cache window: the next call fails, including one from a pipeline already running.

Before revoking, read the "Last used" column: it tells you whether the key is still in service.

Afterwards, the refusal separates three cases, because the actions they call for are different:

Code What it means What you do
API_KEY_REVOKED Somebody withdrew it Create a new one
API_KEY_EXPIRED It reached its date Replace it
API_KEY_UNKNOWN This key never existed Check what your CI is sending

These are three 401 responses.

Delete a workspace a key targets

Refused, with 409 WORKSPACE_HAS_ACTIVE_KEYS and the names of the keys that block it.

Two possible moves before trying again: revoke the key, or remove that workspace from its scope. An already revoked or expired key blocks nothing, since it opens nothing.

Provision one workspace per branch

That is what org:write is for:

# Open a workspace for the current branch
curl -X POST https://api.facteur.eu/workspaces \
  -H "Authorization: Bearer fk_your_key" \
  -H "content-type: application/json" \
  -d '{"name": "staging-PR-1234"}'

Two things to know:

  • The workspace it creates is not in the key's scope. A key does not widen itself. If your tests have to read the mail of that new workspace, target "all workspaces" when you create the key.
  • The plan's ceiling applies. A plan that does not sell another workspace answers 402 WORKSPACE_LIMIT_REACHED.

Manage who reaches a workspace

A key carrying org:write can list a workspace's members, add one and remove one.

That brings nobody into your organization. The person you name has to be a member already; anybody else is refused with NOT_AN_ORGANIZATION_MEMBER. What changes is which workspaces a colleague already present can open.

Inviting remains the act a key never performs.

Known limits

  • No IP address restriction. A key works from any address: there is no allowlist for runners that leave through a fixed address.