Base URLs, tokens, and concepts

Hosts and purposes

Ave separates user-facing pages from API calls. Sending API requests to the sign-in host is the most common integration mistake.

Host	Used for
`aveid.net`	Sign-in and consent pages, OIDC discovery, JWKS
`api.aveid.net`	API calls (token exchange, userinfo, public-key lookup)
`devs.aveid.net`	Registering and managing apps

✅ POST https://api.aveid.net/api/oauth/token
✅ GET  https://aveid.net/.well-known/openid-configuration
❌ POST https://aveid.net/api/oauth/token   ← token API is on api.aveid.net

Identity model

When a user signs in with Ave, they sign in as a specific identity — not just a user account. The same person can have multiple identities.

Concept	Description
`identityId`	Stable UUID for an identity. Use this as your primary key for user data.
`handle`	The identity’s username (e.g. `alice`). Can be changed by the user.

Don’t store data keyed by handle — it can change. Always use identityId (the sub claim in JWTs) as your stable identifier.

Token types

A successful token exchange returns up to four tokens, each with a different purpose:

access_token — opaque bearer token

An opaque string accepted by Ave’s own API endpoints (mainly /api/oauth/userinfo). Not a JWT — you cannot decode it. It expires after 1 hour.

access_token: "ave_at_..."

access_token_jwt — signed JWT for Ave APIs

A signed JWT with aud: https://aveid.net. Use this when calling Ave API endpoints that accept JWTs. Do not use it as the login token for your app API; use id_token or your own app session for that.

access_token_jwt: "eyJ..."

Verify using the jwks_uri from your issuer’s OIDC discovery document ({issuer}/.well-known/openid-configuration). For Ave, this is https://aveid.net/.well-known/jwks.json.

id_token — OIDC identity token

A signed JWT with aud set to your clientId. Use this to establish a user session in your app, or with OIDC-aware services like Convex. Only returned when openid scope is granted.

id_token: "eyJ..."

refresh_token — long-lived session token

An opaque token you can exchange for a fresh set of access/ID tokens without re-authenticating the user. Only returned when offline_access scope is granted. Rotated on every use — store the new one immediately.

refresh_token: "rt_..."

id_token and access_token_jwt are both JWTs but have different audiences. The id_token audience is your clientId. The access_token_jwt audience is https://aveid.net. This matters for any library that validates JWT audience.

Scopes

Scopes are space-separated strings requested during authorization. They control which claims appear in tokens and whether Ave delivers encryption keys.

Scope	What it unlocks
`openid`	Returns `id_token`. Required for OIDC flows.
`profile`	Adds `name`, `preferred_username`, `picture` to userinfo
`email`	Adds `email` to userinfo
`offline_access`	Returns `refresh_token` for long-lived sessions
`user_id`	Returns the account-wide user ID alongside the identity ID
`e2ee:symmetric`	Delivers a per-identity AES-256 app key
`e2ee:asymmetric`	Delivers a per-identity P-256 keypair and enables public-key lookup
`e2ee:reset`	Rotates the app’s keys for this identity; combine with an encryption mode

openid, profile, email, and offline_access are allowlisted per app in the developer portal. Requesting one outside the allowlist returns invalid_scope. user_id and the encryption scopes are requested per sign-in and always require user consent. See Scopes and claims.

Token endpoint field casing

The Ave token endpoint (POST /api/oauth/token) accepts OAuth-standard snake_case body fields and their camelCase equivalents.

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "redirect_uri": "...",
  "code_verifier": "..."
}

Either spelling works for each field. The SDK sends grantType, clientId, redirectUri, and codeVerifier as JSON. Form-encoded bodies, which most OAuth libraries send, work too.

Overview

Core concepts

Base URLs, tokens, and concepts

Hosts and purposes

Identity model

Token types

Scopes

Token endpoint field casing

​Hosts and purposes

​Identity model

​Token types

​Scopes

​Token endpoint field casing

Hosts and purposes

Identity model

Token types

Scopes

Token endpoint field casing