> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.esectra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform catalog administration

> The deployment owner decides which country and document combinations flows may offer.

The verification capability catalog is global to a deployment: every organisation's flows select from it. It is administered by the **platform operator** - the deployment owner - with a credential that is neither a tenant API key nor a Control role. A tenant `ADMIN` administers one organisation and cannot change the catalog; an API key acts for one tenant and cannot either.

## The operator credential

Set `ESECTRA_PLATFORM_OPERATOR_TOKEN` on the API container. In production it must be at least 32 characters, or the API refuses to start; generate one with `openssl rand -base64 48`. Unset, the `/v1/platform/*` routes do not exist (they answer `404 PLATFORM_ADMINISTRATION_DISABLED`). The token is compared in constant time against a hash held in memory, is never logged, and is recorded in the audit trail as the actor `platform-operator` under the reserved tenant `platform`.

**Self-hosting:** the organisation running the deployment is its platform operator. Keep the token with the deployment's other secrets, on the API host only, and never hand it to a customer tenant.

## Read the catalog

```bash theme={null}
curl "$ESECTRA_BASE_URL/v1/platform/catalog" \
  -H "Authorization: Bearer $ESECTRA_PLATFORM_OPERATOR_TOKEN"
```

Every entry, enabled or not, ordered by country and document type. The shipped catalog is Nigeria (`NG_NIN_SLIP`, `NG_PASSPORT`, `NG_DRIVING_LICENCE`) and Ghana (`GH_PASSPORT`, `GH_DRIVING_LICENCE`). Passports name the `TD3_MRZ` reader and the NIN slip its own; the driving licences name no reader and are offered as `MANUAL_REVIEW` extraction - the document is captured, inspected and used for the face comparison, and a reviewer reads it. The catalog cannot name a reader the inference service does not implement.

## Add an entry

```bash theme={null}
curl -X POST "$ESECTRA_BASE_URL/v1/platform/catalog" \
  -H "Authorization: Bearer $ESECTRA_PLATFORM_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "KE",
    "document_type": "NATIONAL_ID",
    "display_name": "Huduma card",
    "reader": null,
    "capture": { "document_number_required": true },
    "enabled": true
  }'
```

`country` is an ISO-3166-1 alpha-2 code; `document_type` one of `PASSPORT`, `DRIVING_LICENCE`, `NATIONAL_ID`, `RESIDENCE_PERMIT`, `NIN_SLIP`, `OTHER`; `reader` one of `NG_NIN_SLIP`, `TD3_MRZ`, or `null`. The code is derived: `KE_NATIONAL_ID`. An entry that exists answers `409 CAPABILITY_EXISTS`; one that does not validate `422 INVALID_CAPABILITY`.

## Change, disable, enable

```bash theme={null}
# Rename, change the reader (null clears it), change capture rules
curl -X PUT "$ESECTRA_BASE_URL/v1/platform/catalog/KE_NATIONAL_ID" \
  -H "Authorization: Bearer $ESECTRA_PLATFORM_OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Huduma Namba card"}'

# Stop new flows selecting it
curl -X POST "$ESECTRA_BASE_URL/v1/platform/catalog/KE_NATIONAL_ID/disable" \
  -H "Authorization: Bearer $ESECTRA_PLATFORM_OPERATOR_TOKEN"

# And back
curl -X POST "$ESECTRA_BASE_URL/v1/platform/catalog/KE_NATIONAL_ID/enable" \
  -H "Authorization: Bearer $ESECTRA_PLATFORM_OPERATOR_TOKEN"
```

Nothing is ever deleted. Disabling keeps the entry; new drafts cannot select it and a draft that holds it can no longer be published, while every published flow revision and every open session that already carries it keeps the snapshot it took. Each change bumps the entry's `revision` and writes one audit event (`CAPABILITY_CREATED`, `CAPABILITY_UPDATED`) with the previous and new state; asking for the state an entry is already in changes nothing and writes nothing.

## Postman

Create an environment with `ESECTRA_BASE_URL` and `ESECTRA_PLATFORM_OPERATOR_TOKEN`, set the collection's authorisation to *Bearer Token* with `{{ESECTRA_PLATFORM_OPERATOR_TOKEN}}`, and import the OpenAPI document from this site; the `Platform` tag holds the five requests above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.