Opens an Orchestrator session for one of your users from a form your server signs. Post this as a top-level browser navigation (an auto-submitting form), not from JavaScript: the response is a 302 that the browser follows.

Signing

Sign with your parent customer's signing key (Settings → SSO), even when resource_id is a sub-organization. Build the canonical string by joining these values with :, in this order:

1. resource_id
2. timestamp, exactly as posted
3. email, exactly as posted
4. role, only when you send one (trimmed)
5. encodeURIComponent(return_to), only when you send one (return_to is trimmed first)

Sign it with HMAC-SHA256 and send the digest as 64 lowercase hex characters in token. name is not signed.

Rules

• timestamp is Unix time in seconds and must be within 120 seconds of Grid's clock, in either direction.
• Each token works once. A replay is rejected.
• resource_id is the session target: your parent customer or one of its direct sub-organizations.
• An existing Orchestrator user on the target opens their own session. A parent user opening a sub-organization views it as that sub-organization, if they are allowed to. Any other user on a different customer is rejected.
• A new email creates a user on the target. role sets that user's role (default Case Reviewer); Admin and Billing are rejected. role and name are ignored for existing users.
• return_to keeps only origin and path. In production it must be https and not localhost.

Response

302 to {Orchestrator host}/auth/callback?code=<one-time code>&method=sso. The host is this environment's Orchestrator (production, staging, or a review app). Orchestrator redeems the code (single use, valid 2 minutes) and opens the session. Tokens are never placed in the URL.

Errors also redirect, to /auth/callback?method=sso&error=<CODE>: SSO_LAUNCH_FIELD_REQUIRED, SSO_LAUNCH_TIMESTAMP_INVALID, SSO_LAUNCH_TARGET_INVALID, SSO_SIGNATURE_INVALID, SSO_LAUNCH_REPLAYED, SSO_SIGNING_KEY_NOT_FOUND, SSO_MODULE_NOT_ENABLED, CUSTOMER_NOT_FOUND, SSO_USER_CUSTOMER_MISMATCH, SSO_USER_NOT_ORCHESTRATOR, SSO_ROLE_NOT_ASSIGNABLE, SSO_ROLE_NOT_FOUND, FORBIDDEN, BAD_REQUEST.