Sign in with Avatarada — OpenID Connect (PKCE)

Issuer and discovery

Avatarada's OIDC engine is Ory Hydra. Point your OIDC client at the issuer and let it read every endpoint from the discovery document — do not hard-code endpoint paths.

<issuer>/.well-known/openid-configuration

The discovery document lists the authorization, token, userinfo, JWKS and revocation endpoints. Read them from there; the authorize and token URLs below are examples only.

<issuer>/.well-known/jwks.json

Authorization Code + PKCE

Use the Authorization Code flow with PKCE (code_challenge_method=S256). Send the user to the authorize endpoint, then exchange the returned code at the token endpoint.

• PKCE (S256) is recommended for every client and mandatory for public clients.
• Public clients hold no secret — a public-client authorize without a code_challenge is rejected and no code is issued.
• Confidential clients authenticate with a client secret; PKCE is still recommended.

Authorize URL (template)

<issuer>/oauth2/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &scope=openid%20identity%20wallet:read
  &audience=https%3A%2F%2Fapi.avatarada.io
  &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

To call the wallet-data API you must request BOTH the wallet:read scope AND the wallet-API audience (https://api.avatarada.io) on the authorize request. Selecting wallet:read in the developer console already adds that audience to the client's allow-list, but the authorize request must still ask for it — otherwise the access token carries no audience and the wallet-data API rejects it with 403 insufficient_scope.

Token exchange (curl)

curl -X POST "<issuer>/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your.app/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_PKCE_VERIFIER"
  # Confidential clients authenticate with the client secret instead of (or in
  # addition to) PKCE, e.g. -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET".

Register a client

Register and manage clients in the developer console — there is no public dynamic registration. The console talks to Hydra on your behalf.

• Choose public (no secret, PKCE mandatory) or confidential (a client secret).
• Add one or more redirect URIs: absolute https URLs (http only for loopback in development), no wildcards or fragments.
• Pick the scopes your app needs; selecting wallet:read also adds the wallet-API audience to this client's allow-list so you can call the wallet-data API. You must still request that audience on each authorize request (see the authorize URL below).
• A confidential client's secret is shown exactly once at creation (and on rotation) — store it then; it is never shown again.

Scopes and claims

Request only the scopes you need. A scope you request that Avatarada does not grant is shown on the consent screen but dropped from the grant.

Identity: sub = stake address

The ID token sub is the user's mainnet stake address (stake1…) — that is their Avatarada identity. With the identity scope, the same address is repeated in the explicit stake_address claim. No wallet or on-chain data is ever placed in a token.

{
  "iss": "<issuer>",
  "aud": "YOUR_CLIENT_ID",
  "sub": "stake1u9...",          // the user's mainnet stake address = their identity
  "stake_address": "stake1u9..." // present only when the "identity" scope is granted
}

Wallet data is never embedded in a token: it is served by the wallet-data API against the access token's audience (https://api.avatarada.io).

Each user also has an inbound-only inbox at stake1…@avatarada.io (the stake address from the sub). A service with a verified sending domain and the inbox:send scope can deliver mail there; everything else is silently dropped.

Consent and disconnect

Avatarada's own session is the sole basis for single sign-on, and the user can revoke a connection at any time.

• The user's local Avatarada session is the only basis for accepting a login — a local sign-out fully ends single sign-on.
• Login acceptance is never remembered at the provider, so every authorize re-mediates through the session.
• When a user disconnects your app (from their account connections page), its access and refresh tokens are revoked immediately — introspection reads active:false at once. Signing out of Avatarada only ends the user's own session; it does NOT revoke an already-issued access token, which stays valid until it expires.

Next: read wallet data

Once you hold a wallet:read access token, call the wallet-data API to read the user's public on-chain data.