Authentication

OAuth 2.1, PKCE, scopes, tokens, and how partner apps authenticate to the Swapnice API.

The Partner API uses OAuth 2.1 with authorization-code + PKCE. It does not accept consumer-app Firebase tokens, implicit grants, or password grants.

What you store

Credential	Who holds it	Shown
app_id	Partner backend	After Swapnice creates the app
client_id	Partner backend and public clients	After create
client_secret	Confidential backend only	Once, at create or rotation
Access token	Short-lived, in memory or a secret store	From /oauth/token
Refresh token	Confidential backend, if offline_access was granted	Rotates on use

Public or browser clients can start a connection session. They must not hold client_secret.

Discovery

curl https://api.sandbox.swapnice.com/.well-known/oauth-authorization-server

The document lists authorization_endpoint, token_endpoint, introspection_endpoint, revocation_endpoint, supported grants, and S256 as the only code-challenge method.

Authorization-code + PKCE

1. Create a code verifier and S256 challenge

   The verifier is 43–128 characters of unreserved URL-safe text. The challenge is the Base64URL SHA-256 of that verifier, without padding.

2. Request an authorization code

   POST /oauth/authorize with response_type=code, exact redirect_uri, customer_id, space-separated scope, and code_challenge_method=S256.

3. Exchange the code

   POST /oauth/token with grant_type=authorization_code, code_verifier, client_id, client_secret, and the same redirect_uri.

4. Call the API

   Send Authorization: Bearer <access_token>. Access tokens last about 15 minutes. Authorization codes last about 5 minutes and are single-use.

TypeScript

const token = await swapnice.oauth.token({
  grant_type: "authorization_code",
  client_id: process.env.SWAPNICE_CLIENT_ID!,
  client_secret: process.env.SWAPNICE_CLIENT_SECRET!,
  code,
  code_verifier: verifier,
  redirect_uri: process.env.SWAPNICE_REDIRECT_URI!,
});

Example token response:

{
  "access_token": "swa_at_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "connections:write consent:write events:write profile:read claims:read intents:read"
}

Do not use Postman’s built-in OAuth 2.0 helper. Authorize is a JSON POST that includes customer_id. See the request walkthrough.

Introspect and revoke

curl -X POST "$SWAPNICE_API_BASE_URL/oauth/introspect" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "token": "'"$ACCESS_TOKEN"'" }'

curl -X POST "$SWAPNICE_API_BASE_URL/oauth/revoke" \
  -H "Content-Type: application/json" \
  -d '{ "token": "'"$ACCESS_TOKEN"'" }'

Introspect requires tokens:introspect. Revoke does not send a Bearer header. Tokens are hashed at rest.

Redirect URIs

• Must be HTTPS in production (localhost is acceptable in sandbox)
• Must match a registered URI exactly — no wildcards, no trailing-slash drift
• Browser/public clients also need allowed origins if they call from a web SDK

Scope templates

Start from a template. Add scopes only when a call needs them.

Template	Scopes	Use
Ingest only	consent:write events:write	Send consented events
Connect and ingest	connections:write connections:read consent:write consent:read events:write events:read	Full SDK connect flow
Profile reads	previous + profile:read claims:read intents:read	Read resolved intelligence
Full partner	previous + customers:write customers:read webhooks:write webhooks:read	Production integration
Admin / platform	apps:read apps:write entries:read entries:write ontologies:read ontologies:write tokens:introspect tokens:revoke workflows:read	Trusted internal or enterprise

scope on authorize is a space-separated string. It must be a subset of the app’s allowed scopes.

Common errors

Code	Cause	Fix
invalid_client / invalid_client_id	Unknown client	Confirm sandbox client_id
invalid_grant	Code expired, reused, or PKCE mismatch	Re-run authorize with a fresh verifier
invalid_scope	Scope not allowed on the app	Ask Swapnice to add the scope, or drop it
invalid_redirect_uri	URI does not match registration	Copy the registered value exactly
missing_bearer_token	No Authorization header	Attach the access token
401 on /v1/*	Token expired or missing scope	Re-authorize; tokens last ~15 minutes

Security rules the API enforces

• PKCE S256 only (plain is rejected)
• Short-lived access tokens
• Hashed secrets and tokens at rest
• Exact redirect match
• Purpose-checked ingest and reads after you have a token
• Authorization failures stay generic and never include secrets

Next: consent and account linking or the request walkthrough.