Skip to main content

​
Overview

The Verify Group platform uses a two-track authentication model:
TrackBest forCredential
API KeysServer-to-server, scripts, backend servicesvg_live_ prefixed key
OAuth 2.0Web apps, SPAs, mobile apps with user contextclient_id + client_secret

​
1. Register your developer account

After your organisation is onboarded, register a developer account: 
curl -X POST https://uat.gateway.verify-group.io/api/v1/developers/register \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "'$ORG_ID'", "type": "organization", "tier": "starter"}'

​
2. Create an OAuth App

Register your application to get a client_id and client_secret: 
curl -X POST https://uat.gateway.verify-group.io/api/v1/oauth-apps \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Integration","type":"server","organizationId":"'$ORG_ID'","scopes":["kyc:read","claims:read","voice:read"]}'
Response — save the clientSecret immediately, it is shown once: 
{
  "data": {
    "clientId": "vg_client_...",
    "clientSecret": "vg_secret_...",
    "status": "active"
  }
}

​
3. Choose your access pattern

​
Option A — API Key (server-to-server)

# Generate a key
curl -X POST https://uat.gateway.verify-group.io/api/v1/developers/$DEVELOPER_ID/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"name":"production","permissions":["kyc:read","claims:read"]}'

# Use it
curl https://uat.gateway.verify-group.io/api/v1/kyc/verifications \
  -H "X-API-Key: vg_live_xxxxx" \
  -H "X-Organization-ID: $ORG_ID"

​
Option B — Client Credentials (machine-to-machine OAuth)

curl -X POST https://uat.gateway.verify-group.io/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials&scope=kyc:read claims:read"

​
4. Top up credits

API calls consume tokens from your organisation wallet. Purchase more: 
curl -X POST https://uat.gateway.verify-group.io/api/v1/tokens/purchase \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID" \
  -d '{"amount": 1000, "currency": "KES"}'
Check your balance: 
curl https://uat.gateway.verify-group.io/api/v1/tokens/me/balance \
  -H "Authorization: Bearer $ACCESS_TOKEN"

​
5. Make your first KYC call

curl -X POST https://uat.gateway.verify-group.io/api/v1/kyc/verifications \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"participant_id":"<uuid>","type":"individual","scenario":"identity","payload":{"identifier_type":"national_id","identifier_number":"12345678","country":"KE"}}'

​
Supported scopes

ScopeAccess
openidOIDC ID token
profileName and profile fields
emailEmail address
org:readOrganisation info
kyc:readRead KYC results
kyc:writeCreate and sync KYC verifications
claims:readRead claims
claims:writeCreate and update claims
voice:readRead voice sessions and transcripts
evidence:readRead evidence files
evidence:writeUpload and review evidence
tokens:readRead token balance and transactions

​
Enterprise SSO

If your organisation uses Azure AD, Okta, or another SAML/OIDC IdP, configure Single Sign-On so your team members log in with their corporate credentials. See the Enterprise SSO guide.