A normal user token acts on the user's own resources. To act on behalf of an organization — managing its memberships, activities, rewards, or webhooks — you need an org-scoped token. Endpoints that require one are labelled "Requires an org-scoped token" in the API Reference.

You get one with the OAuth 2.0 token exchange grant (RFC 8693): you trade a user's access token for a new token that carries the organization's context and the user's role in it.

Requirements

• A valid user access token (from the authorization code flow) for a user who is an owner, manager, or member of the organization.
• The organization's UUID.

Exchange the token

curl -X POST "https://api.davi.social/oauth2/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=USER_ACCESS_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "resource=org:ORGANIZATION_UUID"

The resource parameter names the target organization as org:<organization_uuid>.

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Use the returned access_token as the bearer token on org endpoints.

Things to know

• No refresh token is issued for an exchanged token (per RFC 8693). When it expires, refresh the underlying user token and exchange again.
• The exchange fails if the user isn't a member of the target organization, or if your app wasn't granted the scopes the org endpoints require.
• The new token embeds the user's role in the org (owner / manager / member); endpoints enforce role in addition to scope.

Next

• Scopes — the permissions org endpoints require.
• Webhooks — the most common reason to need an org-scoped token.