Skip to content

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.

  • 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: bearer for the credential the dashboard-facing routes take — a Supabase JWT, or an Appwarden API token sent as Bearer aw_… — and appwardenApiToken for 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.
  • Response payload shapes. Success bodies are the { content, context, error } envelope with content left 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/ws answers an upgrade at the fetch level rather than as a route, so it is not in the document.

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 example write: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 in Authorization — it is not bearer-prefixed — or in the appwardenApiToken field of a JSON body. On the dashboard-facing routes, send it as Authorization: Bearer <token>: a bearer credential that starts aw_ 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.

Any OpenAPI 3.1 generator can consume the document. With openapi-typescript, for example:

Terminal window
npx openapi-typescript https://api.appwarden.io/openapi.json -o appwarden-api.d.ts

The 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.