> ## 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.

# Authentication

> How to obtain and use OAuth2 access tokens for the didx:verify API.

## 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`:

```bash theme={null}
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"
```

### Response

```json theme={null}
{
  "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:

```bash theme={null}
-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:

```bash theme={null}
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.

## Consent Requirement

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.

```json theme={null}
{
  "ConsentReceived": true,
  ...
}
```

<Warning>
  Requests with `ConsentReceived: false` will be rejected. This field is audited and required for regulatory compliance.
</Warning>

## 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                     |