Davi Developers LogoDavi Developers

Documentation

Scopes

Request the right permissions and understand user consent.

Scopes are the permissions your app requests. The user sees them on the consent screen and can decline. Request the minimum your integration needs.

These are OAuth scopes — permissions on a token. They are unrelated to reward trigger scopes, which describe when a reward fires.

Requesting scopes

Pass a space-separated scope parameter to /authorize (and optionally when you refresh, to narrow it):

scope=openid profile activity:read reward:read

Your app can only request scopes it was granted when registered. The token response echoes the scopes actually granted in its scope field — always honor that rather than assuming you got everything you asked for.

OpenID Connect scopes

Davi supports the standard OIDC scopes:

  • openid — enables OIDC and returns an id_token.
  • profile, email — standard profile / email claims.
  • offline_access — request a refresh token for long-lived access.

Resource scopes

Beyond OIDC, scopes follow a resource:action shape (some add a sub-resource, e.g. activity:attendees:manage). Families you'll encounter include activity:*, membership:*, org:*, reward:*, profile:*, card:*, contact:*, wallet:*, and file/upload scopes. Examples:

| Scope | Grants | |---|---| | activity:read | View activities | | activity:attend | Mark attendance / check in | | membership:read | View memberships | | org:read, org:update | Organization data and management | | reward:read, reward:redeem | View and redeem rewards | | profile:read | View profiles | | user:read | Read the user |

Don't hard-code a scope list. Scope names are still being consolidated while v1 is in preview. Fetch the live catalogue from GET /oauth2/scopes — it returns every scope with its description and sensitivity, grouped by category — and check the API Reference, where each endpoint documents the scope it requires.

Sensitive scopes

A scope can be marked sensitive, which makes the consent screen highlight it with an extra warning. org:delete and wallet:decrypt are examples. The authoritative flag is the sensitive field on each entry from GET /oauth2/scopes.

First-party scopes

Some scopes have an audience of first-party — they exist for Davi's own applications and cannot be issued to a third-party app (they're prefixed internal:). Webhook management is one of these, which is why webhooks are configured in the dashboard rather than via the API. If a scope you need isn't grantable, it's likely first-party.

Scope is necessary, not sufficient

For organization resources, a scope alone doesn't authorize an action — the caller's role in that organization must also allow it. A request can therefore be refused even with the right scope, and the error tells you which side denied it. See Org-scoped tokens.

The first time a user authorizes your app, Davi shows a consent screen listing the requested scopes (sensitive ones called out separately). Once granted, subsequent authorizations for the same scopes skip the prompt. Users can revoke your app from their Davi settings at any time.

Machine-to-machine (client credentials)

For server-to-server calls with no user present, a confidential app can use the client_credentials grant. It returns an access token scoped to the scopes you request (and were granted) — no user, no refresh 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=client_credentials" \
  -d "scope=profile:read activity:read reward:read"

Next