Davi Developers LogoDavi Developers

Documentation

Authentication

How Davi's OAuth 2.0 / OpenID Connect authentication works.

Davi is a full OAuth 2.0 authorization server and OpenID Connect provider. Every API request authenticates with a bearer token:

Authorization: Bearer <access_token>

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

Endpoints

The OAuth endpoints live under https://api.davi.social/oauth2 — note this is not under the /api/v1 prefix used by the rest of the API:

| 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 /scopes | Scope metadata (names, descriptions, sensitivity) | | GET /.well-known/openid-configuration | OIDC discovery document | | GET /.well-known/jwks.json | Public keys for verifying token signatures |

The discovery document is the source of truth for these URLs. Fetch /.well-known/openid-configuration and read authorization_endpoint, token_endpoint, jwks_uri, etc. rather than hard-coding them.

Grant types

| Grant | Use it for | Notes | |---|---|---| | authorization_code | Signing in a user | Requires PKCE (S256). See Authorization code. | | 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.

Client types

You choose a client type when you register an app:

  • 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.

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. Fetch the public keys from jwks_uri (from discovery) to verify signatures offline, or call POST /oauth2/introspect to check a token's status server-side.

Registering an app

Apps are registered per organization in the dashboard under Developer → Apps. There you set the client type, redirect URIs, allowed grant types, and scopes, and receive a Client ID (and a one-time Client Secret for confidential apps). See the Quickstart for the walkthrough.

Next