> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/broker-vm-on-appliance/registration.md). # 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 > 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\`]\(#operation/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.
```json {"openapi":"3.0.3","info":{"title":"Cortex Broker Direct Public API (on-appliance)","version":"1.0.0"},"tags":[{"name":"registration","description":"Register the broker against the Cortex tenant using a registration\ntoken previously issued via the tenant-side\n`POST /public_api/v1/brokers/registration_token/` endpoint\n(see `broker-papi.yaml`).\n"}],"servers":[{"url":"https://{broker_host}","description":"The broker appliance's on-board HTTPS listener.","variables":{"broker_host":{"default":"broker.example.local","description":"Operator-chosen hostname or IP of the Broker VM appliance.\nReplace with your broker's actual address.\n"}}}],"security":[{"PublicApiToken":[]}],"components":{"securitySchemes":{"PublicApiToken":{"type":"http","scheme":"bearer","bearerFormat":"opaque","description":"Short-lived (10-minute TTL) opaque API token issued by\n[`generateToken`](#operation/generateToken). Sent as\n`Authorization: Bearer `. A token that expires mid-request\ndoes NOT abort the response (DRF authenticates once at request\nstart).\n"}},"schemas":{"RegisterRequest":{"description":"Body for `registerBroker`. The `token` is opaque to the broker — pass through verbatim from the tenant-side `generateRegistrationToken`.\n","type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":1,"description":"Registration token previously issued by the tenant-side\n`POST /public_api/v1/brokers/registration_token/`.\n"}}},"RegisterSuccessResponse":{"type":"object","description":"Success envelope for [`registerBroker`](#operation/registerBroker).","properties":{"reply":{"$ref":"#/components/schemas/RegisterReply"}}},"RegisterReply":{"description":"Payload of the `registerBroker` success response. The `device_id` is the broker's `PLATFORM_ID` used by the tenant inventory.\n","type":"object","required":["device_id"],"properties":{"device_id":{"type":"string","description":"Broker's `PLATFORM_ID` — the identifier the broker is known\nby in the tenant inventory. Use this with the tenant-side\nAPI to manage the broker from the cloud.\n"}}},"PublicApiErrorResponse":{"type":"object","description":"Canonical envelope for every error (`4xx`/`5xx`) JSON response.\n","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message. Pydantic validation failures\nare rendered as `\": ; : ; ...\"`\n(semicolon-separated) by `format_pydantic_errors`.\n"},"reply":{"nullable":true,"description":"Always `null` on error responses. Present in the envelope to\nkeep the JSON shape consistent with success responses.\n"}}}},"responses":{"Unauthorized":{"description":"Missing, malformed, or expired Bearer token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"}}}},"InitialPasswordRequired":{"description":"`InitialPasswordGateMiddleware` blocked the request because the\nfactory-default admin password has not yet been replaced via\n[`resetInitialPassword`](#operation/resetInitialPassword).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"}}}}}},"paths":{"/public_api/v1/register":{"post":{"tags":["registration"],"operationId":"registerBroker","summary":"Activate the broker against the Cortex tenant","description":"Activate this broker against the Cortex tenant by consuming a\nregistration token previously issued via the tenant-side\n`POST /public_api/v1/brokers/registration_token/` endpoint\n(see `broker-papi.yaml`).\n\nOn success, the broker is registered and the response carries\nthe broker's `device_id` (the `PLATFORM_ID` that subsequently\nidentifies the broker in the tenant inventory).\n\n- **Authentication:** Bearer token from [`generateToken`](#operation/generateToken).\n- **Idempotency:** **idempotent** — calling again with the same\n (or any) valid token while already registered returns the\n existing `device_id`. Re-registration / DR is out of scope.\n- **Error opacity:** registration failures (proxy errors,\n connection failures, FQDN issues, invalid token shape) are\n collapsed into a single generic `500` response — internal\n detail is captured server-side per CWE-209 to avoid leaking\n configuration to unauthenticated-ish callers.\n","requestBody":{"required":true,"description":"Carries the registration `token` issued by the tenant-side `generateRegistrationToken`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"200":{"description":"Broker registered (or already registered).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterSuccessResponse"}}}},"400":{"description":"Pydantic validation failure (missing or empty `token`), or\nthe token failed a structural validity check before the\ntenant call was made.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InitialPasswordRequired"},"500":{"description":"Registration failed due to an internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiErrorResponse"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/xsiam-api/broker-vm-on-appliance/registration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.