SupportWire Docs

Authentication

Authorize with OAuth 2.0 (authorization code + PKCE) and call the API with a bearer token.

Open in ChatGPT Open in Claude

The SupportWire API uses OAuth 2.0 with the authorization code grant and PKCE. Your app sends an organization admin through a consent screen, receives a one-time code, and exchanges it for a long-lived access token.

The flow

1. Send the user to authorize

Redirect the admin to the authorize endpoint with your client_id, redirect_uri, requested scope, and a PKCE code_challenge.

GET https://api.supportwire.app/api/oauth/authorize
  ?client_id=app_abc123
  &redirect_uri=https://yourapp.com/oauth/callback
  &scope=conversations:read%20contacts:read
  &state=xyz789
  &code_challenge=E9Mroz...
  &code_challenge_method=S256

After the user consents and picks an organization, they are redirected back to your redirect_uri with a code and your state.

2. Exchange the code for a token

From your server (back channel), exchange the code. Authenticate with your client_id/client_secret and include the PKCE code_verifier.

curl -X POST https://api.supportwire.app/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=code_abc123 \
  -d redirect_uri=https://yourapp.com/oauth/callback \
  -d client_id=app_abc123 \
  -d client_secret=secret_xyz \
  -d code_verifier=dBjftJ...
{
  "access_token": "swot_abc123def456…",
  "token_type": "Bearer",
  "scope": "conversations:read contacts:read"
}

Note — Tokens are long-lived and opaque (prefixed swot_). There are no refresh tokens. Org admins can revoke a connection at any time from the dashboard.

3. Call the API

curl https://api.supportwire.app/api/oauth/v1/me \
  -H "Authorization: Bearer swot_abc123def456…"

Actor modes

Each token is bound to (app, organization, actor). The actor chosen at authorize time decides what the token can do.

Actor Bound to Can author? Use for
app the app only No (read + admin ops only) Background integrations, syncing
self a specific user + org Yes — sends messages, notes, manages members Acting on behalf of a person

Writes that author content (messages, notes, new conversations, inviting members) require an actor=self token. Using an actor=app token for these returns 422 actor_self_required.

For actor=self tokens, effective scopes are capped by the user's role — members lose :write scopes that require admin.

Next

See Scopes for the full permission list, then jump into the API Reference.