Skip to main content
PATCH
Update a workspace SSO configuration (not available)

Authorizations

hookie_session
string
cookie
required

The console's sealed session cookie, set by WorkOS AuthKit. Mutating requests also require the X-Requested-With CSRF header.

Path Parameters

sso_config_id
string
required

Response

Not signed in.

error
string
required

Human-readable reason.

retry_after
integer

Seconds to wait. Present on 429.

upgrade_url
string<uri>

Present on a monthly-quota 429, and on a member_limit_reached 403 (the console's Settings → Plan & billing).

reason
string

Machine-readable reason, where the status alone is ambiguous. workspace_suspended (403): the workspace is suspended; delivery_allowance_exhausted (429): a replay was refused because the monthly delivery allowance is used. endpoint_disabled (503): the endpoint is switched off; handshake_failed: a provider URL-verification challenge could not be answered (#193). missing_header, bad_signature, stale_timestamp (401): an endpoint's provider signature check failed; scheme names the check. portal_customer_mismatch (409): a portal token was requested for, or the vendor switched on the endpoint of, a customer other than the one the portal now serves (PORT-2g); customer_id and customer_name name that customer. Agent self-registration (#331), on /v1/agents/register: rate_limited (429), agent_registration_disabled and agent_registration_unavailable (503), invalid_body, invalid_agent_name, invalid_operator_contact, terms_not_accepted (with terms_version), proof_of_work_required, invalid_challenge, challenge_expired, invalid_proof_of_work, invalid_idempotency_key (400), body_too_large (413), already_registered, registration_in_progress, challenge_spent (409, with account_id), daily_cap_reached, source_daily_limit (429), identity_provider_error (502), registration_incomplete (503).

code
enum<string>

Present on a 403 to an OAuth-connected agent, and on a member-limit 403 to anyone. agent_scope_insufficient: the agent's grant is below what the call needs, and widening it would let the call through (see required_scope and manage_url). insufficient_role: the user's OWN workspace role does not allow the call, so no grant can — a workspace owner or admin has to change the user's role first, in the console under Settings → Members. agent_not_permitted: no connected agent or API key may do this at any scope (billing, platform admin, managing connected agents, a destination's signing secret, invites of any kind, changing a role, removing a member, transferring ownership, listing or switching a person's workspaces, and creating API keys). To a self-registered agent account nobody has claimed yet (#331) it also carries claim_required: true: a person must claim the workspace with the claim link from registration before anyone can do it. member_limit_reached (#308): the workspace already has as many members as its plan allows, so an invite cannot be created or accepted; max_members, members and upgrade_url say how many and where to upgrade.

Available options:
agent_scope_insufficient,
insufficient_role,
agent_not_permitted,
member_limit_reached
required_scope
enum<string>

With code: the scope the refused call needs.

Available options:
hookie:read,
hookie:write,
hookie:manage
granted_scopes
string[]

With code: the scopes the agent's grant holds now.

manage_url
string<uri>

With code: "agent_scope_insufficient" only: the console's Settings → Connected agents page, opened on this agent (…/#/settings/agents?client=<client_id>), where its user widens the grant. The change applies on the agent's next request.

scheme
string

Present on a signature 401: the endpoint's verification scheme.

max_members
integer

With code: "member_limit_reached": the plan's member limit.

members
integer

With code: "member_limit_reached": the workspace's members now.

customer_id
string | null

On a portal_customer_mismatch 409: the customer the portal already serves.

customer_name
string | null

On a portal_customer_mismatch 409: that customer's display name, if one was given.

account_id
string

On a 409 from POST /v1/agents/register: the agent account the earlier request created (or is creating). Never accompanied by a credential.

terms_version
string

On a terms_not_accepted 400: the Terms version accept_terms must equal.

claim_required
boolean

With code: "agent_not_permitted", to a self-registered agent account nobody has claimed (#331): the refused action needs a person, who first claims the workspace with the claim link from the registration response (claim.url).