API
The Appwarden REST API publishes its contract as an OpenAPI 3.1 document. Fetch it from the deployment you are calling:
| Deployment | Document |
|---|---|
| Production | https://api.appwarden.io/openapi.json |
| Staging | https://staging-api.appwarden.io/openapi.json |
Fetching the document needs no credentials. Calling the API does — see Authenticating below.
Staging sits behind Cloudflare Access, so an unauthenticated fetch of the staging document is
answered with a redirect to the Access login rather than the document. Send a service token
(CF-Access-Client-Id and CF-Access-Client-Secret) or use production.
What the document describes
Section titled “What the document describes”- Every route the API serves other than its internal ones: the dashboard-facing and middleware routes, the provider webhooks and OAuth callbacks Appwarden receives, and the health check.
- The status codes each route answers, and the error schema behind each one — the shared error envelope (
Unauthenticated,Forbidden,NotFound,BadRequest, …) and the route-specific ones. - The two security schemes, declared per operation, so a generated client knows which calls need a credential:
bearerfor the credential the dashboard-facing routes take — a Supabase JWT, or an Appwarden API token sent asBearer aw_…— andappwardenApiTokenfor the Appwarden API token the middleware routes take. Operations that carry no HTTP credential — the provider webhooks and OAuth callbacks, the health check, the public billing plans — declare no security, because a provider signature or the OAuth state is what authorizes them.
What it does not describe
Section titled “What it does not describe”- Response payload shapes. Success bodies are the
{ content, context, error }envelope withcontentleft unmodelled, so the document is a contract for calling the API rather than a source of response types. - Internal routes. The Cloudflare Access boundary routes the monitor pipeline posts to, and the superadmin scheduled-message routes, are excluded from the published document.
- The WebSocket hub.
/v1/wsanswers an upgrade at the fetch level rather than as a route, so it is not in the document.
Authenticating
Section titled “Authenticating”Two credentials cover the API, and the document says which one a given operation wants.
- Supabase JWT — for the dashboard-facing routes. Send it as
Authorization: Bearer <token>; organization membership and the route’s permission (for examplewrite:integrations) are checked server-side. See Roles and permissions. - Appwarden API token — for the middleware routes under
/v1/appwarden/*, and for the dashboard-facing routes when you automate the API yourself. On the middleware routes, send the token itself inAuthorization— it is not bearer-prefixed — or in theappwardenApiTokenfield of a JSON body. On the dashboard-facing routes, send it asAuthorization: Bearer <token>: a bearer credential that startsaw_is read as an API token, and the route’s declared permission is checked against the token’s own scopes rather than its creator’s. A token is refused on a route that declares no permission, and on any organization other than its own. See API token management.
Generating a client
Section titled “Generating a client”Any OpenAPI 3.1 generator can consume the document. With openapi-typescript, for example:
npx openapi-typescript https://api.appwarden.io/openapi.json -o appwarden-api.d.tsThe document’s version is the deployed API worker’s version, so it is also a quick way to check which release a deployment is running.
The document is unauthenticated, which means it is also a map of the API’s surface. If you find something in it that should not be public, tell us — the internal routes are excluded deliberately, and we would rather hear about the rest.
