Technical Architecture

This page shows how the Identities REST API fits into the platform and the request lifecycles for authentication and the publishWithResponse endpoint.

System Context

The REST API is the front door to an Identities server. Edge face detectors and partner systems authenticate with a JWT and call the API; the API validates permissions and talks to the facial-recognition engine and the Identities database.

Authentication Flow

A client logs in once to obtain a JWT, sends it on every protected call, and refreshes it before it expires.

Publish With Response Lifecycle

publishWithResponse is the synchronous sibling of publish. Where publish is fire-and-forget (returns 200 OK with no body), publishWithResponse runs the detection over RPC and returns the detected faces in the same call.

publish vs. publishWithResponse

	publish	publishWithResponse
Pattern	Fire-and-forget	Synchronous (RPC)
Returns	200 OK (empty body)	FaceEdgePublishResponse with detected faces
Extra options	—	largestFaceOnly, allowDoubleDetection
Use when	You only need to feed the FR engine	You need the detection result back immediately
Permission	Face Publishing	Face Publishing

Security Notes

• All protected endpoints require a valid JWT in the Authorization: Bearer header.
• The JWT encodes the user's roles; each endpoint enforces a specific permission (see each endpoint's Minimum Permission).
• Use HTTPS for all communications. On-premise deployments may use self-signed certificates — the example scripts use curl -k / skip certificate validation for convenience; remove that in production.