Authentication

Overview

didx:verify has two projects. Each project has its own authentication server, and the CustomClient3 endpoints use a third:

Endpoints	Auth server	Scope	Base URL
Marketplace	`sts.uat.securecitizen.cloud`	`sc-citizen`	`citizen.uat.securecitizen.cloud`
Journey (`/journey/*`)	`portalsts.dev.securecitizen.cloud`	`vc-verify`	`verify.dev.securecitizen.cloud`
CustomClient3 (Journey)	`sts.dev.securecitizen.cloud`	`sc-citizen`	`customclients.dev.securecitizen.cloud`

All three use the OAuth2 client_credentials grant. Request a token from the server that matches the endpoint you are calling.

A token is scoped to its own server. A Marketplace sc-citizen token is not accepted by the Journey API, and a Journey vc-verify token is not accepted by the Marketplace API.

Marketplace authentication

Use your Marketplace clientId and clientSecret with the sc-citizen scope:

curl --request POST \
  --url "https://sts.uat.securecitizen.cloud/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data "client_id=your_client_id" \
  --data "client_secret=your_client_secret" \
  --data "scope=sc-citizen"

This token authenticates every Marketplace endpoint on https://citizen.uat.securecitizen.cloud.

Journey authentication

Use your Journey clientId and clientSecret with the vc-verify scope:

curl --request POST \
  --url "https://portalsts.dev.securecitizen.cloud/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data "client_id=your_client_id" \
  --data "client_secret=your_client_secret" \
  --data "scope=vc-verify"

This token authenticates the /journey/* endpoints on https://verify.dev.securecitizen.cloud.

CustomClient3 authentication

Two Journey endpoints are served from https://customclients.dev.securecitizen.cloud rather than the Journey base URL:

POST /CustomClient3/CustomClient3StartProcess
POST /CustomClient3/CustomClient3RequestResult

These endpoints take an sc-citizen token from sts.dev.securecitizen.cloud, not a Journey vc-verify token:

curl --request POST \
  --url "https://sts.dev.securecitizen.cloud/connect/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data "client_id=your_client_id" \
  --data "client_secret=your_client_secret" \
  --data "scope=sc-citizen"

The rule is simple: authenticate against the server that matches the endpoint’s base URL. Each endpoint’s API Reference page shows its base URL and required scope.

Response

All three servers return the same token shape:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsI...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "vc-verify"
}

Using the token

Include the token as a Bearer token in every request:

-H "Authorization: Bearer <access_token>"

Most Marketplace and CustomClient3 requests require "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.

The following endpoints handle consent differently:

Endpoint	Consent field
`POST /Citizen/AccountVerificationService`	Spelled `ConsentRecieved`, and optional
`POST /Citizen/DriversLicenseVerificationService`	`ConsentReceived` is optional
RSA ID document and passport validation endpoints	Also require `SCConsentReceived`: consent for the platform to store the subject’s data
`/journey/*` endpoints	No consent field

Checking system status

Before making Marketplace 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. The response reports NPRStatus, HANISStatus, and NIISStatus. TBC: engineering adding GET /Citizen/Status to the API reference.

HTTP status codes

Code	Meaning
`200`	Success
`401`	Unauthenticated, token is missing or expired
`403`	Unauthorized, your token doesn’t have access to this resource
`500`	Internal server error
`504`	Backend gateway error, DHA is unavailable (CustomClient3 endpoints only)

Overview

Concepts

Quickstart

Overview

Marketplace authentication

Journey authentication

CustomClient3 authentication

Response

Using the token

Checking system status

HTTP status codes

​Overview

​Marketplace authentication

​Journey authentication

​CustomClient3 authentication

​Response

​Using the token

​Consent requirement

​Checking system status

​HTTP status codes

Overview

Marketplace authentication

Journey authentication

CustomClient3 authentication

Response

Using the token

Consent requirement

Checking system status

HTTP status codes