API overview

OAuth + OIDC

Token grants, userinfo, discovery, and delegation management endpoints.

Signing

Signature request lifecycle, verification, and key management.

Security

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

Base URL

https://api.aveid.net

Use api.aveid.net for all API calls. Use aveid.net for user-facing auth pages (sign-in, Connector consent). Never mix the two.

Request conventions

Request bodies use JSON except multipart image uploads. The token endpoint accepts both OAuth-standard snake_case fields and legacy camelCase fields.

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"

Authentication by endpoint family

Public OAuth/OIDC endpoints — no auth required

These endpoints are public and require no credentials:

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 — app public metadata
GET /api/oauth/resource/:resourceKey — Connector resource metadata
POST /api/oauth/token — token grants (credentials validated in request body)

Userinfo requires a bearer token:

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

Session-authenticated OAuth management endpoints

These require an authenticated Ave session (bearer session token or Ave session cookie):

POST /api/oauth/authorize — grant authorization and produce a redirect URL
GET /api/oauth/authorizations — list active authorizations
GET /api/oauth/authorization/:clientId — get authorization for a specific app
GET /api/oauth/delegations — list active Connector grants
DELETE /api/oauth/delegations/:delegationId — revoke a Connector grant

Signing endpoints — app credentials in body

App-facing signing endpoints authenticate with clientId + clientSecret in the request body:

POST /api/signing/request — create a signing request
GET /api/signing/request/:requestId/status — poll request status
GET /api/signing/public-key/:handle — look up an identity’s public key
POST /api/signing/verify — verify a signature

User-facing signing endpoints require a session token:

GET /api/signing/keys — list the user’s signing keys
POST /api/signing/keys/:identityId — create a signing key
PUT /api/signing/keys/:identityId — rotate a signing key
POST /api/signing/requests/:requestId/sign — approve a request
POST /api/signing/requests/:requestId/deny — deny a request

Identity encryption keys

Encryption keys and Ed25519 signing keys are separate key pairs. Encryption endpoints manage each identity’s encrypted private-key envelope:

GET /api/encryption/public-key/:handle — public encryption-key lookup
GET /api/encryption/keys/:identityId — read the authenticated identity’s key envelope
POST /api/encryption/keys/:identityId — create an encryption key
PUT /api/encryption/keys/:identityId — replace its key envelope

Signing-key rotation uses PUT /api/signing/keys/:identityId and requires a signature from the existing signing key. Initial signing-key enrollment requires an authenticated session.

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 + OIDC

Signing

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