> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aveid.net/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Endpoint families, authentication requirements, and request conventions for the Ave OAuth/OIDC and Signing APIs.

<CardGroup cols={3}>
  <Card title="OAuth + OIDC" icon="key" href="/api/oauth-endpoints">
    Token grants, userinfo, discovery, and delegation management endpoints.
  </Card>

  <Card title="Signing" icon="pen-nib" href="/api/signing-endpoints">
    Signature request lifecycle, verification, and key management.
  </Card>

  <Card title="Security" icon="shield" href="/security/best-practices">
    Hardening checklist for token handling, claims validation, and key safety.
  </Card>
</CardGroup>

## Base URL

```
https://api.aveid.net
```

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

## Request conventions

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

<CodeGroup>
  ```bash Token request theme={null}
  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"
    }'
  ```

  ```bash Userinfo request theme={null}
  curl https://api.aveid.net/api/oauth/userinfo \
    -H "Authorization: Bearer ACCESS_TOKEN"
  ```
</CodeGroup>

## Authentication by endpoint family

<AccordionGroup>
  <Accordion title="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>`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Browser login sessions

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.

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