OIDC Provider

VeraID v2.0 can act as a fully compliant OpenID Connect (OIDC) identity provider, enabling your applications to authenticate users and obtain identity tokens directly from VeraID. This eliminates the need for a separate IdP for human users while keeping your NHI governance in the same platform.

Discovery endpoint

Every organization gets a dedicated OIDC discovery URL:

https://app.veraid.io/api/oidc/{orgId}/.well-known/openid-configuration

Replace {orgId} with your organization ID (found in Settings > Organization > General). The discovery document advertises all supported endpoints, grant types, signing algorithms, and scopes.

Tip

All OIDC-compliant libraries (e.g., openid-client for Node.js, authlib for Python) can auto-configure themselves from the discovery URL. Point your library at the URL above and it will fetch all required metadata automatically.

---

Registering an OIDC client

You can register clients through the admin UI or the API.

Via the admin UI

1. Navigate to Settings > Identity Provider > OIDC Clients.
2. Click Register Client.
3. Fill in the required fields:
   • Client Name — A human-readable name (e.g., “Production Dashboard”).
   • Application Type — web, native, or machine (for service-to-service).
   • Redirect URIs — One or more allowed callback URLs.
   • Grant Types — Select the grant types this client may use (see below).
   • Scopes — Select the scopes this client may request.
4. Click Save. The client ID and client secret are displayed once. Store them securely.

Via the API

curl -X POST https://app.veraid.io/api/v1/oidc/clients \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Dashboard",
    "applicationType": "web",
    "redirectUris": [
      "https://dashboard.example.com/callback",
      "https://dashboard.example.com/silent-renew"
    ],
    "grantTypes": ["authorization_code", "refresh_token"],
    "responseTypes": ["code"],
    "scopes": ["openid", "profile", "email", "groups"],
    "tokenEndpointAuthMethod": "client_secret_post"
  }'

Response:

{
  "clientId": "oidc_cl_a1b2c3d4e5f6",
  "clientSecret": "oidc_cs_secret_value_shown_once",
  "name": "Production Dashboard",
  "applicationType": "web",
  "redirectUris": [
    "https://dashboard.example.com/callback",
    "https://dashboard.example.com/silent-renew"
  ],
  "grantTypes": ["authorization_code", "refresh_token"],
  "scopes": ["openid", "profile", "email", "groups"],
  "createdAt": "2026-03-26T10:00:00Z"
}

Caution

The clientSecret is displayed only once at creation time. Store it in a secrets manager immediately. If lost, you must rotate the client secret via the dashboard or API.

---

Supported grant types

Grant Type	Use Case	Requires User Interaction
authorization_code	Web and native apps that authenticate end users via browser redirect	Yes
client_credentials	Machine-to-machine (M2M) service calls with no user context	No
refresh_token	Obtain new access tokens without re-authenticating the user	No
device_code	CLI tools, smart TVs, and other input-constrained devices	Yes (on a separate device)

Authorization Code flow (recommended for web apps)

The standard OAuth 2.0 authorization code flow with PKCE is recommended for all web and native applications:

1. Redirect the user to the authorization endpoint:

https://app.veraid.io/api/oidc/{orgId}/authorize?
  response_type=code&
  client_id=oidc_cl_a1b2c3d4e5f6&
  redirect_uri=https://dashboard.example.com/callback&
  scope=openid profile email&
  state=random_state_value&
  code_challenge=SHA256_challenge&
  code_challenge_method=S256

2. After authentication, VeraID redirects back with an authorization code.
3. Exchange the code for tokens at the token endpoint:

curl -X POST https://app.veraid.io/api/oidc/{orgId}/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&
      code=AUTH_CODE&
      redirect_uri=https://dashboard.example.com/callback&
      client_id=oidc_cl_a1b2c3d4e5f6&
      client_secret=oidc_cs_secret_value&
      code_verifier=ORIGINAL_VERIFIER"

Client Credentials flow (M2M)

For service-to-service authentication where no user is involved:

curl -X POST https://app.veraid.io/api/oidc/{orgId}/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&
      client_id=oidc_cl_a1b2c3d4e5f6&
      client_secret=oidc_cs_secret_value&
      scope=api:read api:write"

Device Code flow

For CLI tools and input-constrained devices:

1. Request a device code:

curl -X POST https://app.veraid.io/api/oidc/{orgId}/device/authorize \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=oidc_cl_a1b2c3d4e5f6&scope=openid profile"

Response:

{
  "device_code": "dev_abc123",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://app.veraid.io/device",
  "verification_uri_complete": "https://app.veraid.io/device?user_code=ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}

2. Display the user_code and verification_uri to the user.
3. Poll the token endpoint until the user completes authorization.

---

Token endpoint authentication methods

When exchanging codes or requesting tokens, the client must authenticate itself. VeraID supports the following methods:

Method	Description	Recommended For
client_secret_post	Client ID and secret sent in the POST body	Web apps, server-side applications
client_secret_basic	Client ID and secret sent in the Authorization: Basic header	Legacy integrations
private_key_jwt	Client authenticates with a signed JWT using its private key	High-security M2M, zero-secret deployments
none	No client authentication (public clients with PKCE)	SPAs, native mobile apps

Set the authentication method when registering the client via the tokenEndpointAuthMethod field.

Note

For public clients (SPAs and native apps), set tokenEndpointAuthMethod to none and always use PKCE (code_challenge and code_verifier). This is the most secure approach for clients that cannot keep a secret.

---

Scopes and claims

Standard scopes

Scope	Claims Included
openid	sub (subject identifier)
profile	name, given_name, family_name, picture, updated_at
email	email, email_verified
groups	groups (array of group names the user belongs to)
roles	roles (array of roles assigned to the user)
org	org_id, org_name, org_plan

Custom scopes

You can define custom scopes that map to additional claims from user attributes or directory data:

curl -X POST https://app.veraid.io/api/v1/oidc/scopes \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "department",
    "description": "Include department information",
    "claims": [
      { "name": "department", "source": "user.department" },
      { "name": "cost_center", "source": "user.metadata.costCenter" }
    ]
  }'

ID token example

A decoded ID token contains the requested claims:

{
  "iss": "https://app.veraid.io/api/oidc/org_abc123",
  "sub": "usr_def456",
  "aud": "oidc_cl_a1b2c3d4e5f6",
  "exp": 1711461600,
  "iat": 1711458000,
  "nonce": "random_nonce_value",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "email_verified": true,
  "groups": ["engineering", "platform-team"],
  "roles": ["admin", "idp-manager"]
}

---

Token lifetimes

Configure token lifetimes per client or use organization-wide defaults:

Token	Default Lifetime	Configurable Range
Access token	1 hour	5 minutes to 24 hours
ID token	1 hour	5 minutes to 24 hours
Refresh token	30 days	1 hour to 90 days
Device code	10 minutes	1 minute to 30 minutes

Update lifetimes via the API:

curl -X PATCH https://app.veraid.io/api/v1/oidc/clients/{clientId} \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenLifetimes": {
      "accessToken": 3600,
      "idToken": 3600,
      "refreshToken": 2592000
    }
  }'

---

JWKS endpoint

VeraID publishes its signing keys at:

https://app.veraid.io/api/oidc/{orgId}/.well-known/jwks.json

Token signatures are RSA (RS256) by default. ES256 is also supported and can be configured per client. Keys are rotated automatically every 90 days with a 7-day overlap period to allow relying parties to update their caches.

---

Next steps

SAML 2.0 IdP

Set up VeraID as a SAML identity provider for enterprise applications. SAML Setup Guide

Authentication Methods

Configure password, passkeys, magic links, and social login options. Authentication Methods

Federation

Connect external identity providers for enterprise SSO. Federation Guide