Sign in with Avatarada — OAuth2

Quickstart

Three steps — the same as integrating any OAuth2 / OpenID Connect provider.

1. Register a confidential client in the developer console and add your redirect URI.
2. Copy your Client ID and Client Secret (the secret is shown only once).
3. Point any standard OAuth2 / OpenID Connect library at the issuer with your Client ID, secret, redirect URI and the openid scope.

Authorization Code flow

Send the user to the authorize endpoint, then exchange the returned code for tokens at the token endpoint, authenticating with your client secret.

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

Do not hard-code these paths — read the authorize, token, userinfo and JWKS endpoints from the discovery document.

Authorize URL (template)

<issuer>/oauth2/auth
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &scope=openid%20identity
  &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
  &state=RANDOM_STATE

Token exchange (curl)

curl -X POST "<issuer>/oauth2/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your.app/callback"

Scopes

Request only what you need; the openid scope is what enables sign-in.

What you get back

With the openid scope you receive an ID token whose sub is the user’s mainnet stake address — their identity. The identity scope repeats it as the 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
}

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.

Reading wallet data

To call the wallet-data API, also request the wallet:read scope AND the wallet-API audience (https://api.avatarada.io) on the authorize request. Selecting wallet:read in the console adds that audience to the client allow-list, but the authorize request must still ask for it.

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, its access and refresh tokens are revoked immediately. A logout only ends the user's session; it does NOT revoke an already-issued access token, which stays valid until it expires.

No client secret? Use PKCE

Browser and mobile apps that cannot keep a secret use a public client with PKCE — the same Authorization Code flow, without a secret.

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.