Authenticate with an API key.
Every request carries a key in the Authorization header:
curl https://api.appenda.app/v1/tables \
-H "Authorization: Bearer $APPENDA_API_KEY"
Keys work over HTTPS only, and only in that header. A key in the query string
is never accepted. A request without a valid key answers 401 with a
WWW-Authenticate header.
Token types
There are two types of API key, and no others.
| Type | Reaches | Acts as |
|---|---|---|
API user token (api-user, recommended) | One workspace | The member who created it, with that member's current role |
Super-admin token (super-admin, developer use only) | Every workspace in the instance | The instance administrator who created it, while they stay one |
Use an API user token for a script or integration. It can do what its owner's role allows, on every route, admin settings included. When the owner's role changes, the token follows; when the owner leaves the workspace, it stops working. Keys have no scopes. Each operation in the API reference states the permission it needs.
Keys made before these two types existed are listed as API user tokens.
A super-admin token names its target workspace with Appenda-Workspace: ws_….
An API user token cannot use that header to reach another workspace.
An API user token follows its owner's approval rules. An action that role
needs approval for is held: the call answers with an approval to poll instead
of running, and the action runs once an approver allows it.
A held call answers its usual success status, so read the body: a hold has
"object": "approval", and its Location header names the approval to poll.
Create a key
- Sign in at appenda.app/account and open API keys.
- Pick the workspace, name the key and choose Create key.
- Copy the secret. It is shown once and never again.
You can also create keys with the API key operations in the API reference. After that, a key list shows each key's name, prefix, last four characters and last use, never the secret.
Rotate a key
- Create a new key.
- Switch your script or integration to the new key.
- Revoke the old key.
Revoke a key
Choose Revoke next to the key on the API keys page, or call the matching revoke operation. Requests with that key are refused at once. Revoking cannot be undone.
If a key leaks, revoke it now. Then check what it changed: in the Appenda app, open History on each table it could reach, or the workspace activity in Version control. Create a new key for any script that still needs access.