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.
- A name. It is what will tell you which one to revoke in six months: "GitHub CI", "Camille's staging".
- 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.
- Where. Tick the workspaces the key reaches, at least one, or choose all workspaces, the ones you create later included.
- 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_ |
The response names the missing permission (permission) |
List workspaces without org:* |
403 API_ |
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_ |
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_ |
Somebody withdrew it | Create a new one |
API_ |
It reached its date | Replace it |
API_ |
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.