Guides
Authentication
Every request is authenticated with a personal API key. A key acts as the person who created it.
Send the key
Create a key in SlimWiki under Profile → API keys. It starts with swk_ and is shown once, when you create it.
Send it in the Authorization header of every request, as a bearer token:
Authorization: Bearer swk_your_keyWith the key in the SLIMWIKI_API_KEY environment variable, a request looks like this:
curl "https://api.slimwiki.com/v1/me" \
-H "Authorization: Bearer $SLIMWIKI_API_KEY"A request with a missing, invalid, revoked or expired key gets a 401 response with the code unauthorized. Session cookies from the SlimWiki app are not accepted; only API keys are.
What a key can access
A key acts as the person who created it, with exactly their access. It can read what that person can read and change what that person can change, and nothing more.
When a key asks for something its owner cannot see, the API answers 404 not_found, the same as for something that does not exist.
Read-only and read-and-write keys
You choose a scope when you create a key:
- A read-only key can only read.
- A read-and-write key can also make changes, where its owner is allowed to.
A read-only key that sends a request which writes gets a 403 response with the code insufficient_scope. These requests write:
- post/v1/pages (Create a page)
- delete/v1/pages/{page_id} (Delete a page)
- post/v1/pages/{page_id}/archive (Archive a page)
- post/v1/pages/{page_id}/restore (Restore a page)
A read-and-write key can still get a 403, with the code forbidden, when its owner is not allowed to make the change. See Errors.
Expiry and revoking
A key can have an expiry date; this is optional. To stop a key from working, revoke it in Profile → API keys. Requests with an expired or revoked key get 401 unauthorized.
Keep keys on the server
API keys are for server-side use: scripts, back-end services, scheduled jobs. Anyone who has your key can act as you, within its scope.