OAuth2 Integration

VeryAI's OAuth2 integration provides secure biometric authentication using a standard OAuth 2.0 / OpenID Connect flow while protecting user privacy through app-scoped identifiers rather than exposing raw biometric data.

When to Use OAuth2

• 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/oauth2

GET /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

Register your app and get credentials on the Getting Started page, or go directly to the Developer Portal.