Authentication Overview

Davi is an OAuth 2.0 authorization server and an OpenID Connect provider. Every API request carries a bearer token:

Authorization: Bearer <access_token>

Tokens are signed JWTs. You get them through one of the grant types below, using the credentials of an app you register in the dashboard.

Registering an app

Register apps per organization in the dashboard under Developer → Apps. There you set the client type, redirect URIs, allowed grant types and scopes. You receive a Client ID, and confidential apps also receive a Client Secret, shown once. The Quickstart walks through it.

Client types

You choose the client type at registration:

Confidential (server-side application): can keep a secret. Authenticates to the token endpoint with client_secret_basic (HTTP Basic) or client_secret_post (form fields), and may use client_credentials.
Public (client-side application: SPA, mobile, desktop): cannot keep a secret. Uses PKCE with token endpoint auth method none.

Grant types

Grant	Use it for	Notes
`authorization_code`	Signing in a user	Requires PKCE (`S256`). See Sign-in.
`refresh_token`	Keeping a user session alive	Rotates the refresh token. Scope may be narrowed, never widened.
`client_credentials`	Machine-to-machine (no user)	Confidential clients only. No refresh token issued.
`urn:ietf:params:oauth:grant-type:token-exchange`	Acting on behalf of an org	Exchanges a user token for an org-scoped token.

response_types_supported is code. code_challenge_methods_supported is S256.

Machine-to-machine (client credentials)

For server-to-server calls with no user present, a confidential app uses the client_credentials grant. The access token carries the scopes you request, limited to those your app was granted. There is no user and 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"

Endpoints

The OAuth endpoints live under https://api.davi.social/oauth2, not under the /api/v1 prefix the rest of the API uses.

Endpoint	Purpose
`GET /authorize`	Start the authorization code flow
`POST /token`	Exchange a code, refresh, or run client-credentials / token-exchange
`GET /userinfo`	OIDC claims for the current access token
`POST /introspect`	Check whether a token is active (RFC 7662)
`POST /revoke`	Revoke a token (RFC 7009)
`GET /.well-known/openid-configuration`	OIDC discovery document
`GET /.well-known/jwks.json`	Public keys for verifying token signatures

Read these URLs from the discovery document rather than hard-coding them: fetch /.well-known/openid-configuration and use authorization_endpoint, token_endpoint, jwks_uri and the rest.

Token lifetimes

Token	Lifetime
Access token	1 hour
User refresh token	7 days
OAuth client refresh token	30 days
Authorization code	10 minutes

When an access token expires, use the refresh_token grant to get a new one without sending the user through the flow again.

Verifying tokens

Access and ID tokens are RS256-signed. To verify a signature offline, fetch the public keys from jwks_uri (in the discovery document). To check a token's status server-side, call POST /oauth2/introspect.

Sign-in: sign in a user.
Acting as an Organization: act on behalf of an org.
Scopes: request the right permissions.

Documentation