Developers
OAuth2 Integration
VeryAI's Pseudonymous Mode provides secure biometric authentication using an OAuth 2.0 / OpenID Connect flow while protecting user privacy through app-scoped identifiers rather than exposing raw biometric data.
When to Use Pseudonymous Mode
- Apps requiring persistent user identifiers for account linking or activity tracking
- Organizations preferring familiar OAuth-style login flows
- Use cases not requiring zero-knowledge proof anonymity
For maximum privacy without persistent identifiers, see ZK Integration instead.
Authentication Flow
The OAuth2 flow involves five steps:
- 1. Authorization Request — Redirect users to VeryAI Connect with client credentials
- 2. User Verification — Displays QR code for palm scanning via mobile app
- 3. Authorization Code — Returned upon successful verification
- 4. Token Exchange — Converts authorization code to access tokens
- 5. API Access — Uses bearer tokens for protected resources
Base URL
https://api.very.org/oauth2GET /authorize
Initiates the authorization flow. Verifies client_id, redirect_uri, and optional state. If valid, redirects the user to the consent/verification page.
Required Parameters
| Parameter | Type | Description |
|---|---|---|
response_type | string | Must be "code" |
client_id | string | Your application's client ID |
redirect_uri | URI | Pre-registered redirect URI |
scope | string | Must include "openid". Add "offline_access" for refresh tokens. |
Optional Parameters
| Parameter | Type | Description |
|---|---|---|
state | string | Opaque value for CSRF protection |
nonce | string | String value for replay protection |
POST /token
Exchanges an authorization code for access tokens, or refreshes an existing token.
Parameters
| Parameter | Type | Description |
|---|---|---|
grant_type | string | "authorization_code" or "refresh_token" |
client_id | string | Your application's client ID |
client_secret | string | Your application's client secret |
code | string | Authorization code (required for authorization_code grant) |
refresh_token | string | Refresh token (required for refresh_token grant) |
redirect_uri | URI | Must match the original request (required for authorization_code grant) |
Response
| Field | Type | Description |
|---|---|---|
access_token | JWT | Access token (expires in 1 hour) |
id_token | JWT | Contains external_user_id in sub claim |
token_type | string | Always "Bearer" |
expires_in | integer | Token lifetime in seconds |
scope | string | Granted scopes |
refresh_token | JWT | Refresh token (~90 day expiry). Only when "offline_access" scope is granted. |
GET /userinfo
Returns the user's persistent identifier. Requires a valid Bearer access token in the Authorization header.
Response
| Field | Type | Description |
|---|---|---|
sub | string | Stable, pairwise identifier for the end user |
Getting Started
Contact support@very.org to register your app and receive credentials, or visit the Developer Portal to self-serve.