OAuth2 Integration

Pseudonymous Mode

Pseudonymous Mode enables secure biometric authentication using an OAuth 2.0/OpenID Connect flow. Instead of exposing biometric data or raw user IDs, Very issues a secure, app-scoped external_user_id for each user. This lets you identify and re-verify users across sessions while keeping all sensitive information within Very.

---

When to Use This Mode

Use Pseudonymous Mode if your app:

• Needs a persistent identifier for each user (to link accounts, track activity, or manage rewards).

• Wants a familiar OAuth-like login flow for smoother onboarding.

• Doesn’t need zero-knowledge proofs for anonymity.

For apps that need maximum privacy with no persistent IDs, use Anonymous Mode.

Demo

Veros OAuth Demoveros-web-oauth-demo.vercel.app

How It Works

The flow follows the OAuth 2.0 Authorization Code flow security:

1. Authorization Request: Your app redirects the user to Very Connect page with required parameters

2. User Verification: Very displays a QR code for palm scanning via the Very mobile app

3. Authorization Code: Upon successful verification, Very redirects back with an authorization code

4. Token Exchange: Your app exchanges the code for access tokens and user ID

5. API Access: Use the access token to access protected resources

Endpoints

Base URL: https://api.very.org/oauth2

Step 1: Start Authorization

Endpoint: GET /oauth/authorizeRequired Parameters:

• response_type=code (fixed value)

• client_id - Your app's client ID (provided by Very)

• redirect_uri - Must match registered redirect URI exactly

• scope - Must include openid, optionally offline_access for refresh tokens

• state (recommended) - CSRF protection token (max 500 characters)

• nonce (optional) - Value included in ID token for request/response correlation

Response:

• 302 Redirect to Very Connect consent page

Step 2: Handle Callback

After successful verification, Very redirects to your redirect_uri:

https://yourapp.com/callback?
  code=AUTH_CODE&
  state=random_state_value

Step 3: Exchange Code for Tokens

Endpoint: POST /oauth/token

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

• grant_type=authorization_code

• client_id - Your app's client ID

• client_secret - Your app's client secret

• code - Authorization code from callback

• redirect_uri - Same URI used in authorization request

Success Response (200):

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

Token Details:

• access_token: JWT for API access (1 hour expiry)

• id_token: OIDC identity token containing user's external_user_id in sub claim

• refresh_token: Long-lived token for getting new access tokens (only if offline_access scope requested)

Refresh Tokens

Endpoint: POST /oauth/token

Parameters:

• grant_type=refresh_token

• client_id - Your app's client ID

• client_secret - Your app's client secret

• refresh_token - Valid refresh token

UserInfo Endpoint

Endpoint: GET /oauth/userinfo

Authentication: Bearer token (access_token)

Getting Started

1. Register Your App: Contact Very via [email protected] to receive your client_id, client_secret, and register your redirect URIs

2. Implement OAuth Flow: Follow the standard OAuth 2.0 authorization code flow

3. Handle Tokens: Store refresh tokens securely, use access tokens for API calls