Authentication

Overview

didx:verify has two projects, and each has its own authentication server:

Project	Auth server	Scope	Used by
Marketplace	`citizen.uat.securecitizen.cloud`	`sc-citizen`	All Marketplace endpoints, plus the CustomClient3 endpoints under Journey
Journey	`portalsts.dev.securecitizen.cloud`	`vc-verify`	The `/journey/*` endpoints on `verify.dev.securecitizen.cloud`

Both 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://citizen.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. It also authenticates the CustomClient3 endpoints in the Journey project, which are served from the Marketplace platform and use sc-citizen (see Journey endpoints on the Marketplace platform).

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.

Response

Both 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>"

Journey endpoints on the Marketplace platform

Two Journey endpoints are served from the Marketplace platform rather than the Journey base URL:

Endpoint	Base URL	Auth
`POST /CustomClient3/CustomClient3StartProcess`	`customclients.dev.securecitizen.cloud`	`sc-citizen`
`POST /CustomClient3/CustomClient3RequestResult`	`customclients.dev.securecitizen.cloud`	`sc-citizen`

The rule is simple: authenticate against the server that matches the endpoint’s base URL. These two endpoints sit on the Marketplace platform, so they take a Marketplace sc-citizen token even though they belong to a Journey flow. Each endpoint’s API Reference page shows its base URL and required scope. Every 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.

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.

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

Overview

Concepts

Quickstart

Overview

Marketplace authentication

Journey authentication

Response

Using the token

Journey endpoints on the Marketplace platform

Checking system status

HTTP status codes

​Overview

​Marketplace authentication

​Journey authentication

​Response

​Using the token

​Journey endpoints on the Marketplace platform

​Consent requirement

​Checking system status

​HTTP status codes

Overview

Marketplace authentication

Journey authentication

Response

Using the token

Journey endpoints on the Marketplace platform

Consent requirement

Checking system status

HTTP status codes