Authentication

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

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"
}

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.

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