API Specs

OAuth2

Server URLs:

• Production: https://api.very.org/oauth2
• Development: http://localhost:3000/oauth2

GET /authorize

Start the OAuth-style authorization flow. Verifies client_id, redirect_uri, and optional state. If valid, redirects to the consent/verification page with an auth_request_id for further processing.

Parameters

Parameter	Required	Type	Description
response_type	Yes	enum	Must be "code"
client_id	Yes	string	Your application client ID
redirect_uri	Yes	URI	Pre-registered redirect URI
scope	Yes	string	Space-separated scopes. Must include "openid". Use "offline_access" for refresh tokens.
state	No	string	Opaque value for CSRF protection
nonce	No	string	String value for replay protection

Responses

Code	Description
302	Redirects to consent or palm verification UI
400	Bad request
500	Server error

POST /token

Exchange an authorization code for tokens. After successful palm verification, exchanges an authorization code for the corresponding external_user_id.

Content-Type: application/x-www-form-urlencoded

Request Body

Parameter	Required	Type	Description
grant_type	Yes	enum	"authorization_code" or "refresh_token"
client_id	Yes	string	Your client ID
client_secret	Yes	string	Your client secret
code	Conditional	string	Authorization code (required for authorization_code grant)
refresh_token	Conditional	string	Refresh token (required for refresh_token grant)
redirect_uri	Conditional	URI	Must match original request (required for authorization_code grant)

Response (200)

Field	Type	Description
access_token	JWT	JWT access token for accessing protected resources. Include as Bearer {access_token} in the Authorization header.
token_type	enum	Always "Bearer"
expires_in	integer	Lifetime in seconds of the access token
scope	string	Space-separated list of granted scopes
id_token	JWT	OIDC ID Token. sub claim === external_user_id.
refresh_token	JWT	Only provided when "offline_access" scope is granted.
refresh_token_expires_in	integer	Lifetime in seconds of the refresh token (optional)

Error Responses

Code	Description
400	Bad request
401	Unauthorized
500	Server error

GET /userinfo

Standard OIDC UserInfo endpoint. Returns claims about the subject (sub) represented by the Bearer Access Token presented in the Authorization header. Requires scope=openid. Only returns claims the user originally consented to — never private biometric templates.

Security: Bearer Auth (JWT)

Response (200)

Field	Type	Description
sub	string	Stable, pairwise identifier for the end user (same value as the sub claim in the ID Token).

Error Responses

Code	Description
401	Unauthorized — missing or invalid token
403	Forbidden — insufficient scope
500	Server error