Registration

Register the broker against the Cortex tenant using a registration token previously issued via the tenant-side POST /public_api/v1/brokers/registration_token/ endpoint (see broker-papi.yaml).

Activate the broker against the Cortex tenant

post

Activate this broker against the Cortex tenant by consuming a registration token previously issued via the tenant-side POST /public_api/v1/brokers/registration_token/ endpoint (see broker-papi.yaml).

On success, the broker is registered and the response carries the broker's device_id (the PLATFORM_ID that subsequently identifies the broker in the tenant inventory).

• Authentication: Bearer token from generateToken.
• Idempotency: idempotent — calling again with the same (or any) valid token while already registered returns the existing device_id. Re-registration / DR is out of scope.
• Error opacity: registration failures (proxy errors, connection failures, FQDN issues, invalid token shape) are collapsed into a single generic 500 response — internal detail is captured server-side per CWE-209 to avoid leaking configuration to unauthenticated-ish callers.

Authorizations

AuthorizationstringRequired

Short-lived (10-minute TTL) opaque API token issued by generateToken. Sent as Authorization: Bearer <token>. A token that expires mid-request does NOT abort the response (DRF authenticates once at request start).

Body

Body for registerBroker. The token is opaque to the broker — pass through verbatim from the tenant-side generateRegistrationToken.

tokenstring · min: 1Required

Registration token previously issued by the tenant-side POST /public_api/v1/brokers/registration_token/.

Responses

200

Broker registered (or already registered).

application/json

Success envelope for registerBroker.

400

Pydantic validation failure (missing or empty token), or the token failed a structural validity check before the tenant call was made.

application/json

401

Missing, malformed, or expired Bearer token.

application/json

403

InitialPasswordGateMiddleware blocked the request because the factory-default admin password has not yet been replaced via resetInitialPassword.

application/json

500

Registration failed due to an internal error.

application/json

post/public_api/v1/register

POST /public_api/v1/register HTTP/1.1
Host: broker.example.local
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "token": "<registration-token-from-tenant>"
}

{
  "reply": {
    "device_id": "6f3a8c7e-1a9b-4c0d-9e21-7f5d3b1c8a02"
  }
}