API

Bouée's API is at APP_URL/api/v1, in three levels, as Cloudflare's is:

Apps reach it by OAuth alone. There are no API keys, personal access tokens, basic authentication or session cookies used as bearer tokens, and none are to be added: a key is a password that never expires, gets pasted into scripts and chat, and cannot say which app is using it or be limited to what that app needs.

Apps

An app that acts for people is either public, with no secret (a command-line tool or a desktop app, which proves itself with PKCE alone), or has a client secret (a server). Its redirect URIs are https, or http on 127.0.0.1 or [::1] for an app on the person's own computer, whose port may change between runs (RFC 8252). The authorization returns only to a registered URI.

A person approves an app on the consent screen at APP_URL/oauth/authorize, choosing which of their workspaces it may use. Their latest approval is what the app has. They see and revoke their approvals under Connected apps in the user menu (/user/apps), a workspace's owners see which apps people connected to their workspace and can take their workspace out of an approval, and every approval is recorded in the audit log of each workspace it names.

A token never does more than its person can at the time of each request: an agent who leaves a workspace takes the apps they approved out of it, a blocked person's tokens stop working, and account scopes stop working when someone stops being staff.

A workspace app's or account app's secret is shown once, when it is made or replaced. Replacing it, or deleting the app, ends every token it holds. Either can also be declared in bouee.yaml, with its secret read from the environment, so an integration can be configured before Bouée starts (Automated install).

Scopes

A workspace app may hold workspace scopes only, and an account app account scopes only: staff cannot read a workspace's tickets through the account API, just as the staff role grants no access to them in the console.

An app that acts for people

1. Send the person to the consent screen, with a PKCE challenge (S256; plain is refused) and a state:

   https://support.example.com/oauth/authorize?response_type=code&client_id=bcl_…&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=tickets%3Awrite%20user%3Aread&state=…&code_challenge=…&code_challenge_method=S256

2. They sign in if they need to, choose workspaces and approve. Their browser returns to the redirect URI with code, state and iss (RFC 9207: check it is APP_URL). A declined request returns error=access_denied.

3. Exchange the code within five minutes, once:

   curl -s https://support.example.com/oauth/token \
     -u "bcl_…:bcs_…" \
     -d grant_type=authorization_code -d code=bac_… -d redirect_uri=https://app.example.com/callback -d code_verifier=…

   A public app sends -d client_id=bcl_… instead of -u. The answer:

   { "access_token": "bat_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "brt_…", "scope": "tickets:write user:read" }

4. Refresh before the hour is up with grant_type=refresh_token&refresh_token=brt_…. Every refresh returns a new refresh token and retires the old one. Presenting a retired one again ends the whole chain, because it means someone else has a copy; a retry within ten seconds is only refused. Refresh tokens last 30 days from their issue.

An app that acts as itself

curl -s https://support.example.com/oauth/token -u "bcl_…:bcs_…" -d grant_type=client_credentials

It gets an access token for all its scopes, or for fewer with -d scope=…, and no refresh token: ask again when it expires. A workspace app acts in its own workspace; its replies and notes carry its name.

Revoking

POST /oauth/revoke with token=… and the app's credentials (RFC 7009) ends that token, and a refresh token its whole chain. It answers 200 whatever the token was.

Discovery

• GET /.well-known/oauth-authorization-server (RFC 8414): the endpoints, scopes, grants and methods.
• GET /.well-known/oauth-protected-resource (RFC 9728): the API's resource and its authorization server. A 401 names it in WWW-Authenticate.

Calling the API

Send the access token in the Authorization header, and nowhere else:

curl -s https://support.example.com/api/v1/user -H "Authorization: Bearer bat_…"

• Bodies are JSON (Content-Type: application/json), at most 256 KB of message text.
• Answers are { "data": … }; lists are { "data": [ … ], "next_cursor": "…" }. Pass next_cursor back as cursor for the next page, until it is null; limit is 1–100, 50 by default.
• Errors are { "error": { "code": "…", "message": "…" } }: 400 invalid_request, 401 unauthorized or invalid_token, 403 insufficient_scope (the scope needed is in WWW-Authenticate) or forbidden, 404 not_found (also for a workspace the token cannot reach, so a token cannot learn which exist), 409 conflict, 422 invalid_request, 429 rate_limited with Retry-After.
• Keys are snake_case, times ISO 8601, and statuses and priorities lower case (new, open, pending, resolved, closed; low, normal, high, urgent).
• Rate: 1,200 requests a minute for each person's approval of an app, or for each app acting as itself, and 120 token requests a minute per address.

Endpoints

User

An app acting as itself has no person, and gets 403 here.

Account

A new workspace's owner is owner_email, someone who has signed in before, or the staff member the token acts for. An account app naming nobody leaves it without an owner, for staff to take over in Instance settings.

Workspace

Creating a ticket:

{
  "subject": "Printer on floor 3 is jammed",
  "requester": { "email": "jo@example.com", "name": "Jo" },
  "priority": "high",
  "tags": ["printers"],
  "message": { "body": "It shows error E52.", "from": "requester" }
}

message.from is requester for what the customer wrote, as a ticket that arrived by email would hold (the team is notified and the requester gets the usual acknowledgment), or team for a reply to the requester, or with "internal": true a note. Ticket writes follow the console's rules: a reply to a closed ticket is refused, Resolved and Closed wait for the workspace's required fields, and an agent's first reply makes them the owner of an unassigned ticket (an app is never made one).

What keeps it OAuth-only

src/lib/__tests__/api-oauth-only.test.ts fails when:

• a Better Auth plugin that issues keys or accepts sessions as bearer tokens (apiKey, bearer, oneTimeToken) is imported, or an API-key package is added;
• anything but the API's bearer check (src/lib/api/auth.ts) and the token endpoint's client authentication (src/lib/oauth/clients.ts) reads a credential header such as Authorization or X-API-Key;
• the schema gains an API key or personal token table.

Secrets, codes and tokens are stored only as SHA-256 hashes, and carry a prefix (bcs_, bac_, bat_, brt_) so a leaked one says what it is. oauth-postgres.test.ts runs the flows against PostgreSQL (Testing (docs/testing.md in the app repository)).

Webhook signing secrets, such as the one Resend signs incoming email with, are not API credentials: they prove a delivery came from the provider, and grant nothing.