> ## Documentation index
> Fetch the complete documentation index at: https://developer.rhombus.com/llms.txt
> Use it to discover all available pages before exploring further.

# Generate federated session token

> Generate a federated session token for your organization, with your role. The token stops working when the credential that generated it (an API token, OAuth grant or mobile session) is revoked or expires. Federated session tokens cannot generate federated session tokens. A web console session can generate one only for a PANE origin (https://<pane>.pane.rhombus.com), for at most an hour: that is how the PANE gateway gives each pane its viewer's token.

```http
POST https://api2.rhombussystems.com/api/org/generateFederatedSessionToken
```

EU organizations send the same request to `https://api2.eu.rhombussystems.com`.

## Authentication and parameters

- `x-auth-apikey` (header, required): Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints).
- `Authorization` (header): instead of an API key, an OAuth access token (`Bearer <token>`) with the `write` scope.
- `x-auth-scheme` (header, string, default: `api-token`): Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer <token>` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters. One of: `api-token`, `api`, `api-oauth-token`, `federated-token`, `partner-api-token`, `partner-api`, `partner-api-oauth-token`.
- `x-auth-org` (header, string<RUUID>): Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`.

## Request body

Content type: `application/json`. Request object for generating a federated session token.

- `deviceUUid` (string<DeviceFacetUuid> | null): RUUID with optional appended facet information
- `domain` (string | null): Optional. The origin that is allowed to use the federated token: scheme and host, plus a port if non-default (e.g. https://app.example.com), with no path, query or fragment. Any other value, including a bare hostname, is refused with 400 VALIDATION_FAILED. A request made with a token that has a domain must send a matching Origin header or, when it sends no Origin, a Referer on that origin (the Referer may carry a path and query); otherwise it is refused with 403 DOMAIN_NOT_ALLOWED. On the browser API the domain is also the CORS allowed-origin. Omit the field to leave the token unrestricted, which is required for clients that send neither header, such as native and on-prem players. This restricts where a token can be used from a browser; it is not a substitute for treating the token as a bearer credential. Both Origin and Referer are supplied by the client, so a non-browser caller holding the token can send either value at will. Use a short durationSec, and deviceUUid where the token only needs one camera's media, to limit a token that has been extracted.
- `durationSec` (integer<int32> | null): Duration of the federated session token in seconds. Defaults to 3600, maximum 86400 (longer values are clamped to the maximum).

## Response 200

OK. Content type: `application/json`

- `expiresAtMs` (integer<int64> | null): Expiration time of the federated session token, in epoch milliseconds
- `federatedSessionToken` (string<RUUID> | null): base 64 (url-safe) uuid string

## Errors

Also 400, 401, 403, 429, 500, 503 with the standard error body (`errorCode`, `errorMsg`): https://developer.rhombus.com/errors

## OpenAPI

````yaml
openapi: 3.0.1
info:
  title: Rhombus API
  version: "1.0"
servers:
  - description: Production Server
    url: https://api2.rhombussystems.com
security:
  - ApiKeyAuth: []
paths:
  /api/org/generateFederatedSessionToken:
    post:
      description: "Generate a federated session token for your organization, with your role. The token stops working when the credential that generated it (an API token, OAuth grant or mobile session) is revoked or expires. Federated session tokens cannot generate federated session tokens. A web console session can generate one only for a PANE origin (https://<pane>.pane.rhombus.com), for at most an hour: that is how the PANE gateway gives each pane its viewer's token."
      operationId: generateFederatedSessionToken
      parameters:
        - description: "Authentication scheme identifier. Use `api-token` or `partner-api-token` with the `x-auth-apikey` header, `api` or `partner-api` with `x-auth-apikey` plus a client certificate, `api-oauth-token` or `partner-api-oauth-token` with `x-auth-access-token`, and `federated-token` with `x-auth-ft`. A request with `Authorization: Bearer <token>` and no `x-auth-scheme` is treated as OAuth, and `federated-token` may also be sent as the `x-auth-scheme` and `x-auth-ft` query parameters."
          example: api-token
          in: header
          name: x-auth-scheme
          required: false
          schema:
            default: api-token
            enum:
              - api-token
              - api
              - api-oauth-token
              - federated-token
              - partner-api-token
              - partner-api
              - partner-api-oauth-token
            type: string
        - description: "Client organization UUID (22-character RUUID), for partner credentials only. With it the call runs in that client organization with the partner support authority's role. Without it a partner credential runs as the partner organization, which outside the partner endpoints is deprecated (responses carry `Deprecation` and `Sunset: Tue, 05 Jan 2027 00:00:00 GMT`). A malformed value returns 400 `INVALID_AUTH_ORG`; a client organization the partner cannot access returns 403 `PARTNER_CLIENT_ACCESS_DENIED`."
          in: header
          name: x-auth-org
          required: false
          schema:
            format: RUUID
            maxLength: 22
            minLength: 22
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Org_GenerateFederatedSessionTokenRequest"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Org_GenerateFederatedSessionTokenResponse"
          description: OK
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      security:
        - ApiKeyAuth: []
        - oauth2:
            - write
      summary: Generate federated session token
      tags:
        - Org Webservice
components:
  schemas:
    Org_GenerateFederatedSessionTokenRequest:
      description: Request object for generating a federated session token.
      properties:
        deviceUUid:
          description: RUUID with optional appended facet information
          example: AAAAAAAAAAAAAAAAAAAAAA.v0
          format: DeviceFacetUuid
          nullable: true
          type: string
        domain:
          description: "Optional. The origin that is allowed to use the federated token: scheme and host, plus a port if non-default (e.g. https://app.example.com), with no path, query or fragment. Any other value, including a bare hostname, is refused with 400 VALIDATION_FAILED. A request made with a token that has a domain must send a matching Origin header or, when it sends no Origin, a Referer on that origin (the Referer may carry a path and query); otherwise it is refused with 403 DOMAIN_NOT_ALLOWED. On the browser API the domain is also the CORS allowed-origin. Omit the field to leave the token unrestricted, which is required for clients that send neither header, such as native and on-prem players. This restricts where a token can be used from a browser; it is not a substitute for treating the token as a bearer credential. Both Origin and Referer are supplied by the client, so a non-browser caller holding the token can send either value at will. Use a short durationSec, and deviceUUid where the token only needs one camera's media, to limit a token that has been extracted."
          example: https://app.example.com
          nullable: true
          type: string
        durationSec:
          description: Duration of the federated session token in seconds. Defaults to 3600, maximum 86400 (longer values are clamped to the maximum).
          example: 3600
          format: int32
          nullable: true
          type: integer
      type: object
    Org_GenerateFederatedSessionTokenResponse:
      description: Response object containing the generated federated session token.
      properties:
        expiresAtMs:
          description: Expiration time of the federated session token, in epoch milliseconds
          format: int64
          nullable: true
          type: integer
        federatedSessionToken:
          description: base 64 (url-safe) uuid string
          example: AAAAAAAAAAAAAAAAAAAAAA
          format: RUUID
          nullable: true
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Your Rhombus API key. Must be accompanied by the `x-auth-scheme` header set to `api-token` (or `partner-api-token` for partner endpoints).
      in: header
      name: x-auth-apikey
      type: apiKey
    oauth2:
      description: 'OAuth 2.0 authorization code flow with PKCE (`S256`). Send the access token as `Authorization: Bearer <token>`. Each operation lists the scopes it requires; a token without them is refused 403 with `WWW-Authenticate: Bearer error="insufficient_scope"`.'
      flows:
        authorizationCode:
          authorizationUrl: https://console.rhombus.com/oauth/authorize
          refreshUrl: https://auth-web.rhombussystems.com/oauth/token
          scopes:
            physical: Unlock doors and elevators, lockdown, alarms, speakers and robots
            read: View cameras, footage and settings
            write: Change settings and data
          tokenUrl: https://auth-web.rhombussystems.com/oauth/token
      type: oauth2
````
