OAuth: Authorization Code + PKCE

This is the consent-establishing flow — a user signs in, approves scopes, and your app receives a token that acts as them. Run Discovery and onboarding first if you haven’t registered a client yet.

Generate PKCE values and state

Create a code_verifier, derive its S256 challenge, and generate an unguessable state.

import { createHash, randomBytes } from "node:crypto";

// 43–128 characters from [A-Za-z0-9._~-]
const codeVerifier = randomBytes(32).toString("base64url");

// Exactly 43 characters from [A-Za-z0-9_-]
const codeChallenge = createHash("sha256")
  .update(codeVerifier)
  .digest("base64url");

const state = randomBytes(16).toString("base64url");

Store codeVerifier and state server-side, bound to the user’s session — for example in a signed, httpOnly cookie with a short TTL. Never put the verifier in the browser or in a URL.

Redirect the user to the authorization endpoint

GET https://api.getsoundlink.com/api/v1/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=openid%20email%20campaigns%3Aread
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=Wv6bQ2xKpN8sT1yZ

On success the user is redirected (302) to the Soundlink consent screen. This endpoint sends Cache-Control: no-store.

The user approves, and Soundlink returns to your callback

GET https://app.example.com/oauth/callback?code=AUTHORIZATION_CODE&state=Wv6bQ2xKpN8sT1yZ

Compare state against the value you stored before doing anything else, and reject the request if it does not match. If the user declines, you receive ?error=access_denied&state=… instead — treat this as a normal outcome, not a failure.

Exchange the code for a token

The request is application/x-www-form-urlencoded. This grant authenticates with the PKCE verifier and sends no client_secret.

curl -X POST https://api.getsoundlink.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/oauth/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_STORED_CODE_VERIFIER"

const res = await fetch("https://api.getsoundlink.com/api/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,
    redirect_uri: "https://app.example.com/oauth/callback",
    client_id: process.env.SOUNDLINK_CLIENT_ID!,
    code_verifier: storedCodeVerifier,
  }),
});

200 Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.PAYLOAD.SIGNATURE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email campaigns:read"
}

redirect_uri must be identical to the one used in the previous step. Authorization codes are single-use. Store the refresh_token server-side.

Record the organization id

organization_id is a claim on the access token, so no extra request is needed to read it.This is the one value you must persist. Soundlink provides no endpoint that lists which organizations have authorized your client, so an organization whose id you have not stored is one you can no longer act for. Keep it in your own database, keyed to your own user or tenant, along with grant_id if you intend to support disconnecting.

Access token claims

string

The user’s id for authorization_code tokens; your client id for client_credentials tokens — those have no user.

Access tokens are signed with a symmetric key and no JWKS endpoint is published, so you cannot verify their signature. Decode claims only for values you need (such as organization_id) from a token you have just received over TLS, and never treat a decoded claim as proof of anything. Treat tokens as opaque credentials otherwise.

Refresh the access token

When the access token expires, trade the refresh token for a new pair.

curl -X POST https://api.getsoundlink.com/api/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_STORED_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

const res = await fetch("https://api.getsoundlink.com/api/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "refresh_token",
    refresh_token: storedRefreshToken,
    client_id: process.env.SOUNDLINK_CLIENT_ID!,
  }),
});

200 Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.PAYLOAD.SIGNATURE",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "openid email campaigns:read"
}

Every refresh rotates the token. Replace the stored refresh token with the new one. The old one stops working.
A refresh token is valid for 30 days. Each new one gets its own 30 days.
Never reuse a refresh token. Sending one that was already used revokes every refresh token for that grant, and the user must consent again. Two concurrent refreshes with the same token count as reuse, so refresh from one place.
You can narrow, not widen. Send scope to get an access token with fewer scopes. The new refresh token keeps the original scopes. Asking for more returns invalid_scope.
Send client_secret if your client has one. A wrong secret returns 401 invalid_client.

An expired, revoked, or reused refresh token returns 400 invalid_grant. Treat it as a disconnect and send the user through consent again.

Userinfo

GET /api/v1/oauth/userinfo requires a token from the authorization_code grant with the openid scope. A Client Credentials token is rejected with 403 access_denied regardless of its scopes, because it represents an application rather than a user.

cURL

curl https://api.getsoundlink.com/api/v1/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 Response

{
  "sub": "USER_ID",
  "organization_id": "ORGANIZATION_UUID",
  "iss": "https://api.getsoundlink.com",
  "email": "user@example.com"
}

email is present only when the token carries the email scope. Responses send Cache-Control: no-store. Failures return { "error": "…" } with a WWW-Authenticate header:

Status	Code	Meaning
`401`	`invalid_token`	Missing, malformed, expired, or unparseable token
`403`	`insufficient_scope`	Token lacks `openid`
`403`	`access_denied`	Wrong grant type

Send exactly one Authorization header — two are rejected rather than merged.

Once the grant exists, mint unattended tokens with Client Credentials, or jump to Scopes, endpoints and errors to call campaign and metrics routes.

Get started

AI tools

For Developers

Learn

OAuth: Authorization Code + PKCE

Access token claims

Refresh the access token

Userinfo

Next