diff --git a/content/docs/api-v2/authenticated-bots/meet/index.mdx b/content/docs/api-v2/authenticated-bots/meet/index.mdx index 341736c..4a87528 100644 --- a/content/docs/api-v2/authenticated-bots/meet/index.mdx +++ b/content/docs/api-v2/authenticated-bots/meet/index.mdx @@ -89,7 +89,7 @@ Each login supports up to **20 concurrent SSO sessions**. When you dispatch bots Both workspaces and logins track health with a `state` field: - **`active`** — healthy and usable. -- **`invalid`** — the system auto-disabled the resource after a failure (a SAML rejection for workspaces; a bot login failure such as a suspended user or a pending first-time interactive login for logins). Re-enable manually via `PATCH` after fixing the underlying issue. +- **`invalid`** — the system auto-disabled the resource after a failure (a SAML rejection for workspaces; a bot login failure such as a suspended user, or a bot account that never completed its first-time interactive "Welcome to Workspace" login). Re-enable manually via `PATCH` after fixing the underlying issue. When a resource flips to `invalid`, `last_error_message` and `last_error_at` explain why. @@ -101,7 +101,7 @@ The SAML certificate and private key are encrypted at rest using **AES-256-GCM** - Create a meet workspace, configure the Legacy SSO profile in Google Admin Console, prepare Workspace users, and add logins. + Create a meet workspace, configure the Legacy SSO profile, create the bot accounts and complete their welcome flow, then assign the profile and add logins. Use `meet_config` to send authenticated bots, manage pools, configure fallback, and monitor utilization. @@ -137,7 +137,11 @@ Bot creation returns `MEET_LOGIN_UNAVAILABLE` when `meet_config.fallback` is `fa -The system auto-disables a resource after a failure (a SAML rejection for workspaces; a bot login failure for logins). Check `last_error_message`, fix the cause (re-upload a matching cert, complete a user's first-time interactive login, un-suspend the account), then re-enable it with a `PATCH`. +The system auto-disables a resource after a failure (a SAML rejection for workspaces; a bot login failure for logins). Check `last_error_message`, fix the cause (re-upload a matching cert, complete a bot account's first-time interactive "Welcome to Workspace" login, un-suspend the account), then re-enable it with a `PATCH`. + + + +Every new Google Workspace account has to be signed into once, interactively, to complete the **"Welcome to Workspace"** first-run flow — and that has to happen **before** the Legacy SSO profile is assigned to it. Once the profile applies, Google redirects the account's sign-in to Meeting BaaS and its password stops working, so the flow can't be completed by hand. If you're stuck, move the account out of the SSO scope (or set that scope's **Select SSO profile** back to **None**), complete the welcome flow, then re-assign the profile. See [Setup, Step 3](/docs/api-v2/authenticated-bots/meet/setup#step-3--create-the-bot-accounts-and-complete-the-welcome-flow). diff --git a/content/docs/api-v2/authenticated-bots/meet/sending-authenticated-bots.mdx b/content/docs/api-v2/authenticated-bots/meet/sending-authenticated-bots.mdx index 3f39593..36b7d66 100644 --- a/content/docs/api-v2/authenticated-bots/meet/sending-authenticated-bots.mdx +++ b/content/docs/api-v2/authenticated-bots/meet/sending-authenticated-bots.mdx @@ -131,7 +131,7 @@ curl https://api.meetingbaas.com/v2/meet-logins/utilization \ | `MEET_LOGIN_UNAVAILABLE` | No login slot was available (pool saturated or no matching active login) and `fallback` was `fail`. | Add logins, lower concurrency, or set `fallback: "anonymous"`. Watch utilization. | | `MEET_LOGIN_REQUIRED` | The meeting required a signed-in user but the bot could not authenticate. | Ensure `meet_config` is set and the selected login is `active`. | | `MEET_LOGIN_FAILED_SAML_REJECTED` | Google rejected the SAML assertion. | Verify the certificate uploaded to Google Admin matches the workspace cert and the SSO profile is configured and assigned. The workspace auto-flips to `invalid`; re-enable after fixing. | -| `MEET_LOGIN_FAILED_TIMEOUT` | The SSO sign-in did not complete in time. | Confirm the user completed the first-time interactive login and the account isn't suspended; retry. | +| `MEET_LOGIN_FAILED_TIMEOUT` | The SSO sign-in did not complete in time. | Confirm the user completed the first-time interactive "Welcome to Workspace" login (done before the SSO profile was assigned) and the account isn't suspended; retry. | See [Error Codes](/docs/api-v2/error-codes#google-meet-authentication-errors) for the full list. These appear in the bot's `bot.failed` webhook and in the bot details `error_code` field. diff --git a/content/docs/api-v2/authenticated-bots/meet/setup.mdx b/content/docs/api-v2/authenticated-bots/meet/setup.mdx index 0ea0dca..e0dca09 100644 --- a/content/docs/api-v2/authenticated-bots/meet/setup.mdx +++ b/content/docs/api-v2/authenticated-bots/meet/setup.mdx @@ -1,6 +1,6 @@ --- title: Setup -description: Create a meet workspace, configure the Legacy SSO profile in Google Admin Console, prepare Workspace users, and register meet logins +description: Create a meet workspace, configure the Legacy SSO profile in Google Admin Console, create and sign in to the bot accounts, then assign the SSO profile and register meet logins icon: Settings --- @@ -27,8 +27,9 @@ Either way, the SSO profile must target the bot accounts exclusively. Create a **meet workspace** (holds the SAML certificate + key). -Upload the certificate and configure the **Legacy SSO profile** in Google Admin Console. -Create the **Google Workspace users** the bots will sign in as, and complete their first interactive login. +Upload the certificate and configure the **Legacy SSO profile** in Google Admin Console — without assigning it yet. +Create the **Google Workspace users** the bots will sign in as, and sign in to each one to complete the **"Welcome to Workspace"** flow. +**Assign** the Legacy SSO profile to the bot group/OU — only after those accounts have completed their welcome flow. Register a **meet login** for each user. @@ -145,11 +146,35 @@ On the **Legacy SSO profile** page, fill in the following and **Save**: These `/v2/meet-sso/*` URLs are SAML endpoints that Google calls during sign-in — you configure them in Google, you never call them yourself. The certificate you upload here must always match the one stored on the workspace. If you [rotate the keypair](#rotating-the-keypair), upload the new certificate at the same time. + - -### Assign the profile to your bot group (or OU) only + +**Do not assign the profile to your bot accounts yet.** As soon as the Legacy SSO profile covers an account, Google stops accepting its password and redirects sign-in to Meeting BaaS — which means you can no longer complete that account's first-run setup by hand. Create the bot accounts and finish their welcome flow first ([Step 3](#step-3--create-the-bot-accounts-and-complete-the-welcome-flow)), then come back and assign the profile in [Step 4](#step-4--assign-the-sso-profile-to-your-bot-group-or-ou-only). + + +## Step 3 — Create the bot accounts and complete the welcome flow + +Do this **before** assigning the SSO profile in [Step 4](#step-4--assign-the-sso-profile-to-your-bot-group-or-ou-only). For **each** Google account the bots will sign in as: + +1. Create the user in Google Admin Console (for example `bot1@bots.acme.com`) and note the temporary password. +2. **Sign in to that account yourself, in a browser, using that password**, and complete the entire **"Welcome to Workspace"** first-run flow — accept the terms, set a new password if prompted, and dismiss the onboarding screens until you land on a normal signed-in Google page. A freshly created account that has never been signed into interactively cannot be used programmatically: the meet login flips to `invalid` on first use. +3. Set the account language to **English (United States)** to ensure the sign-in and Meet UIs are in the expected state. + + +**Order matters.** Once the Legacy SSO profile is assigned to the account's group/OU, Google redirects its sign-in to Meeting BaaS and the account password no longer works — so the welcome flow can no longer be completed interactively. If you have already assigned the profile, temporarily move the account out of the SSO scope (or set that scope's **Select SSO profile** back to **None**), complete the welcome flow, then assign the profile again. + + + +Create a **Google Group** (for example `bots@bots.acme.com`) and add the bot users as members. Putting this group on a calendar invite lets the assigned bot land in Meet's **verified queue** and bypass the waiting room. You'll reference this group as `email_group` in Step 5. + -Open **Manage SSO profile assignments**. Under **Groups**, pick the group that contains your bot accounts (for example `bots@bots.acme.com`) — or choose the bot **organizational unit**. A new scope starts with **Select SSO profile: None**. +## Step 4 — Assign the SSO profile to your bot group (or OU) only + + +Only do this once **every** bot account from [Step 3](#step-3--create-the-bot-accounts-and-complete-the-welcome-flow) has been signed into and has completed its **"Welcome to Workspace"** flow. Assigning the profile first locks you out of the interactive sign-in needed to finish that flow. + + +Back in **Security → Authentication → SSO with third party IdP**, open **Manage SSO profile assignments**. Under **Groups**, pick the group that contains your bot accounts (for example `bots@bots.acme.com`) — or choose the bot **organizational unit**. A new scope starts with **Select SSO profile: None**. Assign the profile to the bot group/OU **only**. Never assign it to a scope that contains real users, or they will be redirected through the bot IdP. Changes take a few minutes to take effect. - - - - -## Step 3 — Prepare the Workspace users - -For **each** Google account the bots will sign in as: - -1. Create the user in Google Admin Console (for example `bot1@bots.acme.com`). -2. Sign in to that account once interactively and complete the **"Welcome to Workspace"** flow. This first-time interactive login is required before the account can be used programmatically — skipping it causes the login to flip to `invalid` on first use. -3. Set the account language to **English (United States)** to ensure the sign-in and Meet UIs are in the expected state. - - -Create a **Google Group** (for example `bots@bots.acme.com`) and add the bot users as members. Putting this group on a calendar invite lets the assigned bot land in Meet's **verified queue** and bypass the waiting room. You'll reference this group as `email_group` in Step 4. - -## Step 4 — Register a meet login per user +## Step 5 — Register a meet login per user Create one meet login for each Workspace user, referencing the `workspace_id` from Step 1. @@ -230,7 +240,7 @@ Rotate a workspace's certificate and key by sending **both** `cert_pem` and `pri ### Re-enabling an invalid resource -When a workspace or login flips to `invalid`, fix the underlying cause (re-upload a matching cert, complete a user's interactive login, un-suspend the account), then re-enable it with a `PATCH` (`PATCH /v2/meet-workspaces/{workspace_id}` or `PATCH /v2/meet-logins/{credential_id}`). Check `last_error_message` for the reason. +When a workspace or login flips to `invalid`, fix the underlying cause (re-upload a matching cert, complete a user's interactive "Welcome to Workspace" login — temporarily removing it from the SSO scope if needed, un-suspend the account), then re-enable it with a `PATCH` (`PATCH /v2/meet-workspaces/{workspace_id}` or `PATCH /v2/meet-logins/{credential_id}`). Check `last_error_message` for the reason. ### Deleting a workspace diff --git a/content/docs/api-v2/error-codes.mdx b/content/docs/api-v2/error-codes.mdx index 02fefd3..618011c 100644 --- a/content/docs/api-v2/error-codes.mdx +++ b/content/docs/api-v2/error-codes.mdx @@ -207,13 +207,13 @@ These errors apply to [authenticated Google Meet bots](/docs/api-v2/authenticate **Title:** Meet Login Failed — SAML Rejected **Description:** Google rejected the SAML assertion during sign-in. Usually the certificate uploaded to Google Admin Console no longer matches the workspace's certificate, or the Legacy SSO profile is misconfigured or unassigned. -**Resolution:** Verify the certificate in Google Admin matches the workspace `cert_pem` and that the SSO profile points at the `/v2/meet-sso/*` endpoints and is assigned to all users. The workspace auto-flips to `invalid`; re-enable it via `PATCH /v2/meet-workspaces/{workspace_id}` after fixing the configuration. +**Resolution:** Verify the certificate in Google Admin matches the workspace `cert_pem` and that the SSO profile points at the `/v2/meet-sso/*` endpoints and is assigned to the bot group/OU that contains the account. The workspace auto-flips to `invalid`; re-enable it via `PATCH /v2/meet-workspaces/{workspace_id}` after fixing the configuration. ### `MEET_LOGIN_FAILED_TIMEOUT` **Title:** Meet Login Failed — Timeout **Description:** The SSO sign-in flow did not complete within the expected time. -**Resolution:** Confirm the Workspace user completed its first-time interactive "Welcome to Workspace" login and is not suspended, then retry. The login may auto-flip to `invalid`; re-enable it via `PATCH /v2/meet-logins/{credential_id}` after resolving the cause. +**Resolution:** Confirm the Workspace user completed its first-time interactive "Welcome to Workspace" login — this must be done in a browser after the account is created and **before** the Legacy SSO profile is assigned to it — and that the account is not suspended, then retry. The login may auto-flip to `invalid`; re-enable it via `PATCH /v2/meet-logins/{credential_id}` after resolving the cause. ## System Errors diff --git a/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx b/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx index ef42743..298be72 100644 --- a/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx +++ b/content/docs/api-v2/reference/meet-workspaces/createMeetWorkspace.mdx @@ -24,10 +24,11 @@ _openapi: **After creation, you must:** 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile. - 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer" and assign the SSO profile to all users. - 3. Create one or more Workspace users that bots will sign in as, complete the "Welcome to Workspace" interactive login for each, and set language to "English (United States)". - 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. - 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. + 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer". Do not assign the profile yet. + 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the "Welcome to Workspace" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to "English (United States)". + 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow. + 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. + 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH. @@ -114,10 +115,11 @@ Create a meet workspace — the parent resource that holds your SAML cert + priv **After creation, you must:** 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile. - 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer" and assign the SSO profile to all users. - 3. Create one or more Workspace users that bots will sign in as, complete the "Welcome to Workspace" interactive login for each, and set language to "English (United States)". - 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. - 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. + 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable "Use a domain-specific issuer". Do not assign the profile yet. + 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the "Welcome to Workspace" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to "English (United States)". + 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow. + 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`. + 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks. **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH. diff --git a/openapi-v2.json b/openapi-v2.json index 9a396d3..e845868 100644 --- a/openapi-v2.json +++ b/openapi-v2.json @@ -23963,7 +23963,7 @@ ] }, "post": { - "description": "Create a meet workspace — the parent resource that holds your SAML cert + private key for one Google Workspace's SSO config.\n\n A meet workspace represents one Google Workspace whose Legacy SSO profile points at our `/v2/meet-sso/*` endpoints. The cert and key on the workspace are shared by every `meet_login` (Workspace user identity) you attach to it, mirroring how Google Workspace stores a single verification certificate per SSO profile.\n\n **Two creation paths, same response shape:**\n\n - **Server-generated keypair** — pass `generate_keypair: true`. The server creates a self-signed RSA-2048 keypair with 10-year validity. Use this if you don't already have a SAML cert and want the simplest setup.\n - **Bring-your-own keypair** — pass `cert_pem` and `private_key_pem` together. Use this if you want to manage your own crypto or already have a cert/key pair you trust.\n\n Mutually exclusive: provide either `generate_keypair: true` OR (`cert_pem` + `private_key_pem`), not both.\n\n **Response always includes `cert_pem`** so you can upload it to Google's Legacy SSO profile in your Workspace admin console. `private_key_pem` is never returned.\n\n **After creation, you must:**\n 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile.\n 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable \"Use a domain-specific issuer\" and assign the SSO profile to all users.\n 3. Create one or more Workspace users that bots will sign in as, complete the \"Welcome to Workspace\" interactive login for each, and set language to \"English (United States)\".\n 4. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`.\n 5. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks.\n\n **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH.\n\n **Per-team uniqueness:** Each `domain` may exist at most once per team. Attempting to create a duplicate returns 409.\n\n **Error Scenarios:**\n - `409 Conflict`: A workspace for this `domain` already exists.\n - `422 Unprocessable Entity`: Invalid cert/key (parse failure or modulus mismatch); both `generate_keypair` and `cert_pem` provided; neither provided.", + "description": "Create a meet workspace — the parent resource that holds your SAML cert + private key for one Google Workspace's SSO config.\n\n A meet workspace represents one Google Workspace whose Legacy SSO profile points at our `/v2/meet-sso/*` endpoints. The cert and key on the workspace are shared by every `meet_login` (Workspace user identity) you attach to it, mirroring how Google Workspace stores a single verification certificate per SSO profile.\n\n **Two creation paths, same response shape:**\n\n - **Server-generated keypair** — pass `generate_keypair: true`. The server creates a self-signed RSA-2048 keypair with 10-year validity. Use this if you don't already have a SAML cert and want the simplest setup.\n - **Bring-your-own keypair** — pass `cert_pem` and `private_key_pem` together. Use this if you want to manage your own crypto or already have a cert/key pair you trust.\n\n Mutually exclusive: provide either `generate_keypair: true` OR (`cert_pem` + `private_key_pem`), not both.\n\n **Response always includes `cert_pem`** so you can upload it to Google's Legacy SSO profile in your Workspace admin console. `private_key_pem` is never returned.\n\n **After creation, you must:**\n 1. Upload the returned `cert_pem` to Google Admin Console → Security → Set up SSO with third-party IdP → Legacy SSO profile.\n 2. Set Sign-in URL to `https://api.meetingbaas.com/v2/meet-sso/sign-in` and Sign-out URL to `https://api.meetingbaas.com/v2/meet-sso/sign-out` in the same SSO profile. Enable \"Use a domain-specific issuer\". Do not assign the profile yet.\n 3. Create one or more Workspace users that bots will sign in as. Sign in to each new account in a browser and complete the \"Welcome to Workspace\" first-run flow before the SSO profile is assigned to it — once SSO applies, the account password stops working and this flow can no longer be completed. Set language to \"English (United States)\".\n 4. Assign the SSO profile to the bot group or organizational unit only (never to all users), now that each bot account has completed its welcome flow.\n 5. Add `meet_logins` (one per Workspace user) referencing this `workspace_id`.\n 6. Optionally call `POST /v2/meet-workspaces/:workspace_id/verify` to run pre-flight checks.\n\n **Security:** The cert and key are encrypted at rest using AES-256-GCM. `private_key_pem` is never echoed in any response — including subsequent GETs. If you need it back, you must rotate via PATCH.\n\n **Per-team uniqueness:** Each `domain` may exist at most once per team. Attempting to create a duplicate returns 409.\n\n **Error Scenarios:**\n - `409 Conflict`: A workspace for this `domain` already exists.\n - `422 Unprocessable Entity`: Invalid cert/key (parse failure or modulus mismatch); both `generate_keypair` and `cert_pem` provided; neither provided.", "operationId": "createMeetWorkspace", "requestBody": { "content": {