OAuth + OIDC endpoints

The token endpoint accepts both OAuth-standard snake_case fields and legacy camelCase fields. Prefer grant_type, client_id, redirect_uri, and code_verifier in new integrations.

`GET /api/oauth/app/:clientId`

Returns app public metadata and active connector resources. Errors:

404 app not found

`GET /api/oauth/resource/:resourceKey`

Returns active connector resource metadata plus owner app info. Errors:

404 resource not found

`POST /api/oauth/authorize` (session-authenticated)

Used by authenticated Ave session context to grant app authorization and produce redirect URL with code. Body fields include:

clientId

string

required

OAuth client identifier.

redirectUri

string

required

Must exactly match one of the app’s registered redirect URIs.

identityId

uuid

required

Identity selected by the authenticated user.

scope

string

Space-separated scopes; validated against app allowlist.

codeChallenge

string

PKCE challenge for public-client authorization.

encryptedAppKey

string

Required for first E2EE authorization when the app supports E2EE.

requestedResource

string

Connector resource key when connector=true.

requestedScope

string

Connector scope set requested by source app.

Notable behavior:

Scope validation against app allowlist
E2EE key required for E2EE app first authorization
Connector grant create/update with merged scopes

`POST /api/oauth/token`

Supported grant_type values:

authorization_code
refresh_token
urn:ietf:params:oauth:grant-type:token-exchange

authorization_code
refresh_token
token_exchange

{
	"grant_type": "authorization_code",
	"code": "AUTHORIZATION_CODE",
	"redirect_uri": "https://yourapp.com/callback",
	"client_id": "YOUR_CLIENT_ID",
	"code_verifier": "PKCE_VERIFIER"
}

{
	"grant_type": "refresh_token",
	"refresh_token": "rt_...",
	"client_id": "YOUR_CLIENT_ID",
	"client_secret": "YOUR_CLIENT_SECRET"
}

{
	"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
	"subject_token": "SOURCE_APP_ACCESS_TOKEN",
	"resource": "target:resource",
	"scope": "resource.access",
	"client_id": "YOUR_CLIENT_ID",
	"client_secret": "YOUR_CLIENT_SECRET"
}

Authorization code grant

Validates code, expiry, redirect URI, and either:

PKCE verifier (if code challenge present), or
client secret

Returns tokens and user profile payload.

access_token

string

Opaque bearer token accepted by Ave APIs.

access_token_jwt

string

Signed JWT for Ave API authorization. Its audience is Ave’s resource audience.

id_token

string

Returned when openid scope is granted.

refresh_token

string

Returned when offline_access scope is granted.

Refresh token grant

Validates token hash record, client ownership, and revoked/reuse/expiry state, then rotates refresh token and returns new access+refresh. Reuse detection is scoped to the rotated token lineage that was reused, not unrelated refresh tokens held by the same app on other devices.

Token exchange grant (Connector)

Exchanges source app token for delegated target token after grant and scope checks.

FedCM endpoints

Ave also exposes an additive FedCM flow for supported browsers.

`GET /api/oauth/fedcm/config`

Returns the Ave FedCM provider configuration.

`GET /api/oauth/fedcm/accounts`

Returns the currently signed-in Ave identities for the browser session.

`POST /api/oauth/fedcm/assertion`

Returns either:

a short-lived Ave FedCM assertion token, or
a continue_on URL when consent or E2EE setup must finish in a dialog

`POST /api/oauth/fedcm/finalize`

Used by Ave’s continuation UI to turn a completed consent step into a short-lived FedCM assertion.

`POST /api/oauth/fedcm/exchange`

Exchanges a FedCM assertion for the normal token payload. For E2EE apps, the signed FedCM assertion can also carry app_key after Ave’s continuation dialog completes the existing key-unlock flow.

`GET /api/oauth/userinfo`

Authorization: Bearer <access_token_or_access_token_jwt> Returns claims based on granted scopes:

always sub
profile: name, preferred_username, picture
email: email
user_id: only when app allows user_id scope
organization: present when the token was issued with Ave Business organization context

Organization context shape:

{
  "organization": {
    "id": "org_...",
    "name": "Example Co",
    "memberId": "orgmem_...",
    "role": "admin",
    "scopes": ["read", "sign", "approve"],
    "signingAuthority": true,
    "encryptionMode": "standard",
    "keyCustody": "ave_standard",
    "authMethod": "enterprise_sso",
    "ssoConnectionId": "sso_...",
    "e2eeKeyDelivery": "ave_identity_grants_only"
  }
}

Why userinfo may omit fields

Claims are scope-gated. Missing email or profile fields usually means those scopes were not granted.

Accepted token formats

The endpoint accepts both opaque access_token and JWT access_token_jwt when valid and unexpired.

Errors:

401 unauthorized missing bearer token
401 invalid_token invalid/expired/unresolvable token

`GET /api/oauth/organizations`

Authorization: Bearer <access_token_or_access_token_jwt> Lists the active Ave Business organizations for the token identity. Apps use this after a normal sign-in to build a workspace picker, then pass the selected organization id as organizationId in the next authorization request. Optional query:

client_id

string

When present, Ave verifies that the bearer token belongs to that client.

Response:

{
  "organizations": [
    {
      "id": "org_...",
      "name": "Example Co",
      "slug": "example-co",
      "logoUrl": "https://...",
      "role": "admin",
      "scopes": ["read", "sign", "approve"],
      "signingAuthority": true,
      "ssoRequired": true,
      "encryptionMode": "standard",
      "keyCustody": "ave_standard"
    }
  ]
}

Errors:

401 unauthorized missing bearer token
401 invalid_token invalid/expired/unresolvable token
403 invalid_client token does not belong to the requested client_id

`POST /api/oauth/workspaces`

Authorization: Bearer <access_token> Creates a new Ave Business workspace for the token identity. Apps should call this only after the user confirms that the app will create an Ave-managed workspace. Body:

{
  "name": "Example Co",
  "client_id": "YOUR_CLIENT_ID",
  "userConfirmedAveWorkspaceCreation": true
}

name

string

required

Display name for the new Ave workspace.

client_id

string

Verifies that the bearer token belongs to your app.

userConfirmedAveWorkspaceCreation

boolean

required

Must be true. Set it only after your UI tells the user that this creates an Ave Business workspace.

Response:

{
  "organization": {
    "id": "org_...",
    "name": "Example Co",
    "slug": "example-co",
    "logoUrl": null,
    "role": "owner",
    "scopes": ["read", "sign", "approve", "manage_identities", "manage_keys", "manage_sso", "manage_org"],
    "signingAuthority": true,
    "ssoRequired": false,
    "encryptionMode": "standard",
    "keyCustody": "ave_standard"
  }
}

The returned organization.id is the organizationId to use in the next authorization request. Errors:

400 invalid_request mismatched clientId and client_id
400 workspace_creation_failed the identity could not create the workspace
401 unauthorized missing bearer token
401 invalid_token invalid/expired/unresolvable token
403 invalid_client token is not for a registered Ave app or does not match client_id

`GET /.well-known/openid-configuration`

Returns issuer metadata, endpoints, supported scopes, response types, grant types, and signing algs.

`GET /.well-known/jwks.json`

Returns signing key set for JWT verification.

`GET /.well-known/webfinger?resource=...`

Returns issuer discovery link for requested resource.

`GET /api/oauth/delegations` (session-authenticated)

Lists user connector grants with source app and target resource context.

`DELETE /api/oauth/delegations/:delegationId` (session-authenticated)

Revokes active delegation grant and records audit log.

After revocation, token-exchange attempts for that grant fail until the user re-authorizes connector access.

​GET /api/oauth/app/:clientId

​GET /api/oauth/resource/:resourceKey

​POST /api/oauth/authorize (session-authenticated)

​POST /api/oauth/token

​Authorization code grant

​Refresh token grant

​Token exchange grant (Connector)

​FedCM endpoints

​GET /api/oauth/fedcm/config

​GET /api/oauth/fedcm/accounts

​POST /api/oauth/fedcm/assertion

​POST /api/oauth/fedcm/finalize

​POST /api/oauth/fedcm/exchange

​GET /api/oauth/userinfo

​GET /api/oauth/organizations

​POST /api/oauth/workspaces

​GET /.well-known/openid-configuration

​GET /.well-known/jwks.json

​GET /.well-known/webfinger?resource=...

​GET /api/oauth/delegations (session-authenticated)

​DELETE /api/oauth/delegations/:delegationId (session-authenticated)

`GET /api/oauth/app/:clientId`

`GET /api/oauth/resource/:resourceKey`

`POST /api/oauth/authorize` (session-authenticated)

`POST /api/oauth/token`

Authorization code grant

Refresh token grant

Token exchange grant (Connector)

FedCM endpoints

`GET /api/oauth/fedcm/config`

`GET /api/oauth/fedcm/accounts`

`POST /api/oauth/fedcm/assertion`

`POST /api/oauth/fedcm/finalize`

`POST /api/oauth/fedcm/exchange`

`GET /api/oauth/userinfo`

`GET /api/oauth/organizations`

`POST /api/oauth/workspaces`

`GET /.well-known/openid-configuration`

`GET /.well-known/jwks.json`

`GET /.well-known/webfinger?resource=...`

`GET /api/oauth/delegations` (session-authenticated)

`DELETE /api/oauth/delegations/:delegationId` (session-authenticated)