Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.didx.co.za/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

All didx:verify API endpoints require an OAuth2 Bearer token with the sc-citizen scope.

​
Obtaining a Token

Use the OAuth2 client_credentials grant with your clientId and clientSecret: 
curl -X POST "https://citizen.uat.securecitizen.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=sc-citizen"

​
Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsI...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "sc-citizen"
}

​
Using the Token

Include the token as a Bearer token in all API requests: 
-H "Authorization: Bearer <access_token>"

​
Checking System Status

Before making verification calls, you can check whether the Department of Home Affairs (DHA) systems are online: 
curl -X GET "https://citizen.uat.securecitizen.cloud/Citizen/Status" \
  -H "Authorization: Bearer <access_token>"
This returns the current availability of downstream DHA systems so you can anticipate whether calls will succeed or fall back to cached data. Every API request that processes personal information requires "ConsentReceived": true in the request body. This documents that you have obtained the subject’s informed consent to process their personal data, as required by POPIA. 
{
  "ConsentReceived": true,
  ...
}
Requests with ConsentReceived: false will be rejected. This field is audited and required for regulatory compliance.

​
HTTP Status Codes

CodeMeaning
200Success
401Unauthenticated, token is missing or expired
403Unauthorized, your token doesn’t have access to this resource
500Internal server error
504Backend gateway error, DHA is unavailable