API overview

OAuth and OIDC

Token grants, userinfo, discovery, and authorization management.

Encryption

App public-key lookup for end-to-end encrypted apps.

Security

Hardening checklist for token handling, claim validation, and key safety.

Base URL

https://api.aveid.net

Use api.aveid.net for API calls and aveid.net for sign-in pages, discovery, and JWKS.

Request conventions

Request bodies are JSON, except multipart image uploads. The token endpoint accepts OAuth snake_case field names and their camelCase equivalents.

curl -X POST https://api.aveid.net/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "code_verifier": "PKCE_VERIFIER"
  }'

curl https://api.aveid.net/api/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

curl "https://api.aveid.net/api/encryption/app-lookup?client_id=YOUR_CLIENT_ID&handle=alice"

Authentication by endpoint family

Public endpoints

These need no credentials, or carry them in the request body:

GET /.well-known/openid-configuration — OIDC discovery metadata
GET /.well-known/jwks.json — JWT verification keys
GET /.well-known/webfinger — issuer discovery
GET /api/oauth/app/:clientId — public app metadata
POST /api/oauth/token — token grants; client credentials or PKCE verifier in the body
GET /api/encryption/app-lookup — app public-key lookup

GET /api/oauth/userinfo requires Authorization: Bearer <access_token>.

Ave session endpoints

Ave’s own sign-in pages use these with the user’s Ave session. Apps do not call them directly:

POST /api/oauth/authorize — grant authorization and produce the callback URL
GET /api/oauth/authorize/bootstrap/:clientId — app, identities, and existing authorization for the consent screen
GET /api/oauth/authorizations — list the user’s app authorizations
GET /api/oauth/authorization/:clientId — one app’s authorization, including its wrapped keys
DELETE /api/oauth/authorizations/:authId — disconnect an app
PUT /api/oauth/authorization/:clientId/encryption-key — replace a wrapped symmetric app key during recovery

Account encryption keys

Each identity also has its own encryption keypair, separate from per-app keys. Ave’s sign-in pages manage it:

GET /api/encryption/public-key/:handle — public key lookup
GET /api/encryption/keys/:identityId — read the authenticated identity’s wrapped private key
POST /api/encryption/keys/:identityId — create the keypair
PUT /api/encryption/keys/:identityId — replace the wrapped private key

Ave’s browser login sets an HttpOnly session cookie. Login responses contain identities and device details; they do not return a sessionToken field. Device approval starts with POST /api/login/request-approval. Keep both its requestId and requestToken in the requesting browser. Poll POST /api/login/request-status with those two fields. An approved response sets the cookie and delivers the encrypted key transfer once; use that response directly instead of fetching it again. Requests expire after five minutes and remain bound to the original identity if its handle changes. Notifications carry request metadata or a status change. They never include the requester secret or the encrypted key transfer.

CORS behavior

OAuth and OIDC paths are CORS-enabled with controlled origin resolution. Session-protected mutating endpoints with cookies enforce origin allowlisting.

If you use cookie-based session auth for mutating endpoints, requests from disallowed origins are rejected.

OAuth and OIDC

Encryption

Security

​Base URL

​Request conventions

​Authentication by endpoint family

​Browser login sessions

​CORS behavior

Base URL

Request conventions

Authentication by endpoint family

Browser login sessions

CORS behavior