Identity Provider API

This page documents the key API endpoints for VeraID’s v2.0 Identity Provider capabilities. All endpoints require authentication via API key (Bearer token) unless otherwise noted. OIDC and SAML protocol endpoints are accessed by end users and service providers, not API keys.

Auth endpoints

Endpoints for managing authentication configuration and methods.

Password policy

Method	Endpoint	Description
GET	/api/v1/auth/password-policy	Get current password policy
PUT	/api/v1/auth/password-policy	Update password policy

TOTP configuration

Method	Endpoint	Description
GET	/api/v1/auth/totp-config	Get TOTP configuration
PUT	/api/v1/auth/totp-config	Update TOTP configuration

WebAuthn / Passkeys

Method	Endpoint	Description
GET	/api/v1/auth/webauthn-config	Get WebAuthn configuration
PUT	/api/v1/auth/webauthn-config	Update WebAuthn configuration
GET	/api/v1/auth/webauthn/users/{userId}/credentials	List a user’s registered passkeys
DELETE	/api/v1/auth/webauthn/users/{userId}/credentials/{credId}	Remove a user’s passkey

Magic links

Method	Endpoint	Description
GET	/api/v1/auth/magic-link-config	Get magic link configuration
PUT	/api/v1/auth/magic-link-config	Update magic link configuration

Social login providers

Method	Endpoint	Description
GET	/api/v1/auth/social-providers	List configured social providers
POST	/api/v1/auth/social-providers	Add a social login provider
PATCH	/api/v1/auth/social-providers/{providerId}	Update a social provider
DELETE	/api/v1/auth/social-providers/{providerId}	Remove a social provider

---

OIDC Provider endpoints

Client registration

Method	Endpoint	Description
GET	/api/v1/oidc/clients	List OIDC clients
POST	/api/v1/oidc/clients	Register a new OIDC client
GET	/api/v1/oidc/clients/{clientId}	Get client details
PATCH	/api/v1/oidc/clients/{clientId}	Update client configuration
DELETE	/api/v1/oidc/clients/{clientId}	Delete an OIDC client
POST	/api/v1/oidc/clients/{clientId}/rotate-secret	Rotate client secret

Custom scopes

Method	Endpoint	Description
GET	/api/v1/oidc/scopes	List custom scopes
POST	/api/v1/oidc/scopes	Create a custom scope
PATCH	/api/v1/oidc/scopes/{scopeId}	Update a custom scope
DELETE	/api/v1/oidc/scopes/{scopeId}	Delete a custom scope

Protocol endpoints (accessed by relying parties, not API keys)

Method	Endpoint	Description
GET	/api/oidc/{orgId}/.well-known/openid-configuration	OIDC discovery document
GET	/api/oidc/{orgId}/.well-known/jwks.json	JSON Web Key Set
GET	/api/oidc/{orgId}/authorize	Authorization endpoint
POST	/api/oidc/{orgId}/token	Token endpoint
GET	/api/oidc/{orgId}/userinfo	UserInfo endpoint
POST	/api/oidc/{orgId}/revoke	Token revocation endpoint
GET	/api/oidc/{orgId}/end-session	End session (logout) endpoint
POST	/api/oidc/{orgId}/device/authorize	Device authorization endpoint
POST	/api/oidc/{orgId}/introspect	Token introspection endpoint

---

Directory endpoints

Users

Method	Endpoint	Description
GET	/api/v1/directory/users	List users (supports filtering, pagination)
POST	/api/v1/directory/users	Create a new user
GET	/api/v1/directory/users/{userId}	Get user details
PATCH	/api/v1/directory/users/{userId}	Update user attributes
DELETE	/api/v1/directory/users/{userId}	Delete a user
POST	/api/v1/directory/users/{userId}/suspend	Suspend a user
POST	/api/v1/directory/users/{userId}/reactivate	Reactivate a suspended user
POST	/api/v1/directory/users/{userId}/deprovision	Permanently deprovision a user

Query parameters for GET /api/v1/directory/users:

Parameter	Type	Description
status	string	Filter by status: INVITED, ACTIVE, SUSPENDED, DEPROVISIONED
group	string	Filter by group membership
search	string	Search by name or email
page	number	Page number (default: 1)
limit	number	Items per page (default: 20, max: 100)

Groups

Method	Endpoint	Description
GET	/api/v1/directory/groups	List groups
POST	/api/v1/directory/groups	Create a new group
GET	/api/v1/directory/groups/{groupId}	Get group details
PATCH	/api/v1/directory/groups/{groupId}	Update a group
DELETE	/api/v1/directory/groups/{groupId}	Delete a group
GET	/api/v1/directory/groups/{groupId}/members	List group members
POST	/api/v1/directory/groups/{groupId}/members	Add members to a group
DELETE	/api/v1/directory/groups/{groupId}/members/{userId}	Remove a member from a group

---

SCIM 2.0 endpoints

SCIM endpoints follow the RFC 7644 specification. Authentication uses the SCIM bearer token, not the standard API key.

Users

Method	Endpoint	Description
GET	/api/scim/v2/{orgId}/Users	List or search users
POST	/api/scim/v2/{orgId}/Users	Create a user
GET	/api/scim/v2/{orgId}/Users/{id}	Get a user
PUT	/api/scim/v2/{orgId}/Users/{id}	Replace a user
PATCH	/api/scim/v2/{orgId}/Users/{id}	Update a user
DELETE	/api/scim/v2/{orgId}/Users/{id}	Delete a user

Groups

Method	Endpoint	Description
GET	/api/scim/v2/{orgId}/Groups	List or search groups
POST	/api/scim/v2/{orgId}/Groups	Create a group
GET	/api/scim/v2/{orgId}/Groups/{id}	Get a group
PUT	/api/scim/v2/{orgId}/Groups/{id}	Replace a group
PATCH	/api/scim/v2/{orgId}/Groups/{id}	Update a group (add/remove members)
DELETE	/api/scim/v2/{orgId}/Groups/{id}	Delete a group

Service Provider Configuration

Method	Endpoint	Description
GET	/api/scim/v2/{orgId}/ServiceProviderConfig	SCIM service provider configuration
GET	/api/scim/v2/{orgId}/Schemas	Supported SCIM schemas
GET	/api/scim/v2/{orgId}/ResourceTypes	Supported resource types

SCIM filtering

The GET /Users and GET /Groups endpoints support SCIM filter expressions:

GET /api/scim/v2/{orgId}/Users?filter=userName eq "jane@example.com"
GET /api/scim/v2/{orgId}/Users?filter=name.familyName co "Smith"
GET /api/scim/v2/{orgId}/Groups?filter=displayName eq "Engineering"

Supported operators: eq, ne, co, sw, ew, gt, ge, lt, le, and, or, not.

SCIM token management

Method	Endpoint	Description
GET	/api/v1/directory/scim/tokens	List SCIM tokens
POST	/api/v1/directory/scim/tokens	Create a SCIM token
DELETE	/api/v1/directory/scim/tokens/{tokenId}	Revoke a SCIM token

---

SAML endpoints

Service Provider management

Method	Endpoint	Description
GET	/api/v1/saml/service-providers	List SAML service providers
POST	/api/v1/saml/service-providers	Register a new SP
GET	/api/v1/saml/service-providers/{spId}	Get SP details
PATCH	/api/v1/saml/service-providers/{spId}	Update SP configuration
DELETE	/api/v1/saml/service-providers/{spId}	Delete an SP

Protocol endpoints (accessed by service providers)

Method	Endpoint	Description
GET	/api/saml/{orgId}/metadata	IdP metadata document (XML)
GET/POST	/api/saml/{orgId}/sso	Single Sign-On endpoint (accepts GET for redirect binding, POST for POST binding)
GET/POST	/api/saml/{orgId}/slo	Single Logout endpoint

---

Federation endpoints

OIDC federation

Method	Endpoint	Description
GET	/api/v1/federation/oidc	List OIDC federation connections
POST	/api/v1/federation/oidc	Create an OIDC federation connection
GET	/api/v1/federation/oidc/{id}	Get connection details
PATCH	/api/v1/federation/oidc/{id}	Update connection
DELETE	/api/v1/federation/oidc/{id}	Delete connection
POST	/api/v1/federation/oidc/{id}/test	Test connection
GET	/api/v1/federation/oidc/{id}/callback	OIDC callback (used by external IdP)

SAML federation

Method	Endpoint	Description
GET	/api/v1/federation/saml	List SAML federation connections
POST	/api/v1/federation/saml	Create a SAML federation connection
GET	/api/v1/federation/saml/{id}	Get connection details
PATCH	/api/v1/federation/saml/{id}	Update connection
DELETE	/api/v1/federation/saml/{id}	Delete connection
POST	/api/v1/federation/saml/{id}/test	Test connection
GET	/api/v1/federation/saml/{id}/metadata	SP metadata for this connection
POST	/api/v1/federation/saml/{id}/acs	ACS endpoint for this connection

Domain management

Method	Endpoint	Description
GET	/api/v1/federation/domains	List domain-to-IdP mappings
POST	/api/v1/federation/domains/{domain}/verify	Verify domain ownership

General federation

Method	Endpoint	Description
GET	/api/v1/federation	List all federation connections (OIDC + SAML)
GET	/api/v1/federation/{id}	Get any federation connection by ID
PATCH	/api/v1/federation/{id}	Update status (enable/disable)
DELETE	/api/v1/federation/{id}	Delete any federation connection
POST	/api/v1/federation/{id}/test	Test any federation connection

---

Conditional access endpoints

Method	Endpoint	Description
GET	/api/v1/conditional-access/policies	List conditional access policies
POST	/api/v1/conditional-access/policies	Create a policy
GET	/api/v1/conditional-access/policies/{id}	Get policy details
PATCH	/api/v1/conditional-access/policies/{id}	Update a policy
DELETE	/api/v1/conditional-access/policies/{id}	Delete a policy
POST	/api/v1/conditional-access/simulate	Simulate policy evaluation
GET	/api/v1/conditional-access/named-locations	List named locations
POST	/api/v1/conditional-access/named-locations	Create a named location
PATCH	/api/v1/conditional-access/named-locations/{id}	Update a named location
DELETE	/api/v1/conditional-access/named-locations/{id}	Delete a named location

---

Common request/response patterns

Creating an OIDC client

Request:

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": "My Web App",
    "applicationType": "web",
    "redirectUris": ["https://app.example.com/callback"],
    "grantTypes": ["authorization_code", "refresh_token"],
    "scopes": ["openid", "profile", "email"]
  }'

Response (201 Created):

{
  "clientId": "oidc_cl_abc123",
  "clientSecret": "oidc_cs_shown_once",
  "name": "My Web App",
  "applicationType": "web",
  "redirectUris": ["https://app.example.com/callback"],
  "grantTypes": ["authorization_code", "refresh_token"],
  "scopes": ["openid", "profile", "email"],
  "createdAt": "2026-03-26T10:00:00Z"
}

Creating a SCIM user (inbound)

Request (from external IdP):

curl -X POST https://app.veraid.io/api/scim/v2/{orgId}/Users \
  -H "Authorization: Bearer scim_tok_abc123" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "jane@example.com",
    "name": {
      "givenName": "Jane",
      "familyName": "Smith"
    },
    "emails": [
      { "value": "jane@example.com", "primary": true }
    ],
    "active": true
  }'

Response (201 Created):

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "usr_abc123",
  "userName": "jane@example.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Smith"
  },
  "emails": [
    { "value": "jane@example.com", "primary": true }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2026-03-26T10:00:00Z",
    "lastModified": "2026-03-26T10:00:00Z",
    "location": "https://app.veraid.io/api/scim/v2/{orgId}/Users/usr_abc123"
  }
}

Simulating conditional access

Request:

curl -X POST https://app.veraid.io/api/v1/conditional-access/simulate \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_abc123",
    "application": "admin-dashboard",
    "context": {
      "ipAddress": "198.51.100.42",
      "deviceTrust": "compliant",
      "riskScore": 25
    }
  }'

Response (200 OK):

{
  "evaluatedPolicies": [
    {
      "policyId": "pol_abc123",
      "policyName": "Corporate network only",
      "matched": false,
      "reason": "IP is within allowed corporate range"
    }
  ],
  "finalAction": "allow"
}

---

Error codes specific to IdP endpoints

Code	Error	Description
OIDC_CLIENT_NOT_FOUND	404	The specified OIDC client does not exist
INVALID_REDIRECT_URI	400	Redirect URI does not match registered URIs
INVALID_GRANT_TYPE	400	Grant type not allowed for this client
SP_NOT_FOUND	404	SAML service provider not found
SAML_SIGNATURE_INVALID	400	SAML request signature validation failed
FEDERATION_CONN_FAILED	502	Cannot reach the external IdP
DOMAIN_NOT_VERIFIED	400	Domain has not been verified for federation
SCIM_TOKEN_EXPIRED	401	SCIM bearer token has expired
SCIM_FILTER_INVALID	400	Invalid SCIM filter expression
POLICY_CONFLICT	409	Conditional access policy priority conflict