Platform catalog administration

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

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

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

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

Start

Verify

Operate

API reference

Platform catalog administration

The operator credential

Read the catalog

Add an entry

Change, disable, enable

Postman

​The operator credential

​Read the catalog

​Add an entry

​Change, disable, enable

​Postman

The operator credential

Read the catalog

Add an entry

Change, disable, enable

Postman