API Specs

OAuth2

Start OAuth-style authorization flow

get

https://api.very.org/oauth2http://localhost:3000/oauth2

/authorize

Initiates the authorization flow. Verifies client_id, redirect_uri, and optional state. If valid, redirects to the consent/verification page with a auth_request_id for further processing. Partner can then exchange the authorization code for an access token.

Query parameters

response_typestring · enumRequiredPossible values:

client_idstringRequired

redirect_uristring · uriRequired

statestringOptional

noncestringOptional

scopestringRequired

Space-separated list of scopes. Must include "openid" for OpenID Connect authentication. Use "offline_access" to request refresh tokens.

Example: openid offline_accessPattern: ^openid( offline_access)?$

Responses

302

Redirects to consent or palm verification UI

400

API Error

application/json

500

API Error

application/json

get

/authorize

HTTPcURLJavaScriptPython

GET /oauth2/authorize?response_type=code&client_id=text&redirect_uri=https%3A%2F%2Fexample.com&scope=text HTTP/1.1
Host: api.very.org
Accept: */*

No content

Exchange authorization code for external user ID

post

https://api.very.org/oauth2http://localhost:3000/oauth2

/token

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

Body

application/x-www-form-urlencoded

grant_typestring · enumRequired

OAuth 2.0 / OIDC grant type

Possible values:

client_idstringRequired

client_secretstringRequired

codestringOptional

Authorization code (required for authorization_code grant)

refresh_tokenstringOptional

Refresh token (required for refresh_token grant)

redirect_uristring · uriOptional

Redirect URI (required for authorization_code grant)

Responses

200

Token response with external user ID

application/json

400

API Error

application/json

401

API Error

application/json

500

API Error

application/json

post

/token

HTTPcURLJavaScriptPython

POST /oauth2/token HTTP/1.1
Host: api.very.org
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 151

"grant_type='authorization_code'&client_id='text'&client_secret='text'&code='text'&refresh_token='text'&redirect_uri='https://example.com'"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2Nvbm5lY3QudmVyb3MueHl6Iiwic3ViIjoidnUtMTIzNDUiLCJhdWQiOlsiY2xpZW50LWlkLTEyMyJdLCJleHAiOjE2OTk5OTk5OTksImlhdCI6MTY5OTk5NjM5OX0.signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid offline_access",
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2Nvbm5lY3QudmVyb3MueHl6Iiwic3ViIjoidnUtMTIzNDUiLCJhdWQiOlsiY2xpZW50LWlkLTEyMyJdLCJleHAiOjE2OTk5OTk5OTksImlhdCI6MTY5OTk5NjM5OSwibm9uY2UiOiJhYmMxMjMifQ.signature",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2Nvbm5lY3QudmVyb3MueHl6Iiwic3ViIjoidnUtMTIzNDUiLCJ0b2tlbl90eXBlIjoicmVmcmVzaF90b2tlbiJ9.signature",
  "refresh_token_expires_in": 7776000
}

Retrieve user profile from Access Token

get

https://api.very.org/oauth2http://localhost:3000/oauth2

/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 (e.g., email, picture)—never private biometric templates.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

User claims

application/json

401

API Error

application/json

403

API Error

application/json

500

API Error

application/json

get

/userinfo

HTTPcURLJavaScriptPython

GET /oauth2/userinfo HTTP/1.1
Host: api.very.org
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "sub": "text"
}