---
title: "Start a hosted gateway sign-on for a paying tenant (fleet operator)"
method: POST
path: "/v1/hosted-gateway/authorizations"
---

# Start a hosted gateway sign-on for a paying tenant (fleet operator)

`POST /v1/hosted-gateway/authorizations`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/hosted-gateway/authorizations`
- Auth: HTTP bearer

Device-authorization grant (RFC 8628 shaped) by which a paying tenant
of the AgentSafe hosted gateway fleet receives its workspace key
without anyone copying one. The fleet operator (Tenant.py) starts it
with a Microsoft Entra access token for
`api://decionis-operator/Operator.Act` whose `roles` holds the operator
role; who asked (`oid`, sign-in name) is recorded from the verified
token, never from the body, and a body naming a requester is refused.
The customer then approves at `verification_uri_complete` while signed
in to Decionis as `owner_email` by a sign-in that proved that address,
ADMIN or above in a workspace on a paid plan with an active
entitlement, and the operator polls the token endpoint. Codes live 30
minutes; poll every `interval` seconds. Twenty starts per hour per
operator. Without Entra configuration
(DECIONIS_OPERATOR_ENTRA_TENANT_ID, DECIONIS_OPERATOR_ENTRA_CLIENT_ID,
and a well-formed DECIONIS_OPERATOR_ENTRA_CLIENT_APPS when set) every
call answers 503 OPERATOR_AUTH_NOT_CONFIGURED.

## Request body

- HostedGatewayAuthorizationStart
  - `tenant_label` string, required: The tenant id in the fleet registry; www, api, status, admin and console are reserved.
  - `tenant_host` string, required: Where the tenant is served, `<tenant_label>.<fleet domain>`.
  - `upstream` string, required: The tenant's upstream, https without credentials, query or fragment; its origin is what the customer is shown and approves.
  - `owner_email` string, email, required: Only a signed-in user with exactly this email (case-insensitive) may approve or deny.
  - `max_embedded_body_bytes` integer: The tenant's embedding limit, so the approval page states it exactly.

## Response `200`

The authorization; `device_code` stays with the operator, the customer is sent `verification_uri_complete` (or the URI and `user_code`)

- HostedGatewayDeviceAuthorization
  - `authorization_id` string, uuid, required
  - `device_code` string, required: Kept by the operator for polling; never shown to the customer or logged.
  - `user_code` string, required
  - `verification_uri` string, uri, required
  - `verification_uri_complete` string, uri, required
  - `expires_in` 1800, required
  - `interval` 5, required

## Other responses

- `400`: Structured API error
- `401`: OPERATOR_TOKEN_REQUIRED or OPERATOR_TOKEN_INVALID
- `403`: OPERATOR_ROLE_REQUIRED, or OPERATOR_CLIENT_NOT_ALLOWED (the token was issued to a client application other than Azure CLI or one DECIONIS_OPERATOR_ENTRA_CLIENT_APPS names)
- `429`: Structured API error
- `503`: OPERATOR_AUTH_NOT_CONFIGURED, OPERATOR_AUTH_UNAVAILABLE (the tenant's keys could not be read), HOSTED_GATEWAY_RATE_LIMIT_UNAVAILABLE or HOSTED_GATEWAY_CODE_UNAVAILABLE

---

[API](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-policy-evaluation-api/revisions/357f5e459d0c?raw)