This page exchanges a user's access token for an org-scoped token, which acts on behalf of an organization. A normal user token acts only on the user's own resources. Endpoints that need an org-scoped token, such as those managing an organization's memberships, activities, rewards or webhooks, are labelled "Requires an org-scoped token" in the API Reference.

The exchange uses the OAuth 2.0 token exchange grant (RFC 8693). The new token carries the organization's context and the user's role in it.

Requirements

• A valid user access token (from the sign-in flow) for a user on the organization's staff, with the role owner, manager or member.
• 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"

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

Send 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 is not on the target organization's staff, or if your app was not granted the scopes the org endpoints require.
• The new token carries the user's role in the organization (owner, manager or member). Endpoints check the role as well as the scope.

Next

• Scopes: the permissions org endpoints require.
• Receiving Webhooks: set up webhook deliveries for the organization.