> ## Documentation Index > Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update an organization's OIDC connection > Creates the connection (201, in `draft`) or updates it (200). Every save fetches `/.well-known/openid-configuration` and refuses it (422) unless its `issuer` is exactly the one given, its endpoints are https, it supports the `code` response type and RS256 or ES256 ID tokens, and it does not rule out S256 PKCE. The issuer must be a public https URL: internal addresses and redirects are refused. Changing the issuer, client id, client secret, scopes or claims clears the last test result and puts an active connection back to `draft`. Setting `status` to `active` needs the current configuration to have passed a test login (409). Needs the organization's own plan to include SSO (Pay as you go or Enterprise; 402 on Free), and the organization not to be suspended (403); a save that sets `status` to `disabled` is never refused on the plan or a suspension. ## OpenAPI ````yaml /api-reference/openapi.yaml put /v1/organizations/{id}/sso/oidc openapi: 3.1.0 info: title: Qumo Deploy REST API description: > The Qumo Deploy control plane: organizations, projects, signing keys, machine identities, access control, audit and billing. Relay credentials are not issued here: your app signs them with its own [signing keys](/guides/signing-keys). Every operation here is generated against the routes the server registers and checked in CI, so an operation in this reference exists and a route missing from it is deliberately internal (relay mesh, webhooks, probes, operator-only and browser sign-in routes). Errors are JSON objects with one `error` field. What each status code means is in [Error codes](/guides/error-codes); the token scope each permission needs is in [Scopes and permissions](/guides/scopes-permissions). version: 1.0.0 servers: - url: https://api.qumo-deploy.com description: Public API (Bearer tokens only; cookies are ignored) security: [] tags: - name: Account description: The signed-in user's own sessions, tokens, security settings and data. - name: Device flow description: OAuth 2.0 device authorization, used by `qumod login`. - name: Organizations description: Organizations, their members and usage. - name: Projects description: Projects inside an organization. - name: Signing keys description: Keys your app signs relay credentials with. - name: Relays description: Where clients of a broadcast path connect. - name: Identities description: Machine identities, their tokens and IP allowlists. - name: Access control description: Roles, IAM bindings and invitations. - name: Audit description: The audit log and its webhook. - name: Notifications description: Notification policies. - name: Billing description: Plans, usage cost, budgets, invoices and payment methods. - name: Pricing description: Public price list. paths: /v1/organizations/{id}/sso/oidc: parameters: - name: id in: path required: true description: The organization's id. schema: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c put: tags: - Organizations summary: Create or update an organization's OIDC connection description: | Creates the connection (201, in `draft`) or updates it (200). Every save fetches `/.well-known/openid-configuration` and refuses it (422) unless its `issuer` is exactly the one given, its endpoints are https, it supports the `code` response type and RS256 or ES256 ID tokens, and it does not rule out S256 PKCE. The issuer must be a public https URL: internal addresses and redirects are refused. Changing the issuer, client id, client secret, scopes or claims clears the last test result and puts an active connection back to `draft`. Setting `status` to `active` needs the current configuration to have passed a test login (409). Needs the organization's own plan to include SSO (Pay as you go or Enterprise; 402 on Free), and the organization not to be suspended (403); a save that sets `status` to `disabled` is never refused on the plan or a suspension. operationId: putOrganizationOIDCConnection requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OIDCConnectionPutRequest' responses: '200': description: The connection was updated. content: application/json: schema: $ref: '#/components/schemas/OIDCConnection' '201': description: The connection was created, in draft. content: application/json: schema: $ref: '#/components/schemas/OIDCConnection' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' security: - token: [] - cliSession: [] - sessionCookie: [] csrfToken: [] components: schemas: OIDCConnectionPutRequest: type: object required: - issuer - client_id properties: issuer: type: string format: uri description: >- The IdP's issuer, an https URL exactly as its discovery document states it. example: >- https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 client_id: type: string minLength: 1 maxLength: 255 example: 0oa8f2k3l9XyZ1abc357 client_secret: type: string minLength: 8 maxLength: 1024 writeOnly: true description: >- Required on create. Omit on update to keep the stored secret. Encrypted at rest and never returned. scopes: type: array maxItems: 20 items: type: string description: >- Must include `openid`. Omitted, keeps the current scopes (on create, `openid email profile`). example: - openid - email - profile claims: $ref: '#/components/schemas/OIDCClaimMappingUpdate' status: type: string enum: - draft - active - disabled description: >- Omitted, keeps the current status (on create, `draft`). `active` needs a passed test login of the current configuration. OIDCConnection: type: object required: - id - organization_id - protocol - issuer - client_id - client_secret - scopes - claims - status - redirect_uri - created_at - updated_at - last_tested_at - last_test_succeeded_at properties: id: type: string format: uuid example: 8b1d3f5a-2c4e-4f6a-8b0d-1e3f5a7c9b2d organization_id: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c protocol: type: string enum: - oidc issuer: type: string format: uri example: https://acme.okta.com client_id: type: string example: 0oa8f2k3l9XyZ1abc357 client_secret: $ref: '#/components/schemas/OIDCConnectionSecret' scopes: type: array items: type: string example: - openid - email - profile claims: $ref: '#/components/schemas/OIDCClaimMapping' status: type: string enum: - draft - active - disabled description: | `draft` until activated: a draft connection can be tested but is not used to sign in. `active` once a test login of the current configuration passed and it was activated. `disabled` when turned off. redirect_uri: type: string format: uri description: The redirect URI to register at the IdP. example: https://console.qumo-deploy.com/oauth/sso/callback created_at: type: string format: date-time updated_at: type: string format: date-time last_tested_at: type: string format: date-time nullable: true description: >- When the current configuration last finished a test login; cleared when the configuration changes. last_test_succeeded_at: type: string format: date-time nullable: true description: When the current configuration last passed a test login. last_test_result: type: string enum: - passed - exchange_failed - invalid_token - email_missing - email_unverified - discovery_failed - configuration_changed - idp_denied description: The last test login's result; absent before the first. OIDCClaimMappingUpdate: type: object description: >- Claim names to change; an omitted one keeps its current value (on create, the default). Each is 1 to 256 printable characters without spaces. properties: email: type: string example: email email_verified: type: string example: xms_edov name: type: string example: name groups: type: string example: groups OIDCConnectionSecret: type: object description: What the API says about the client secret; never the secret itself. required: - set - last4 properties: set: type: boolean last4: type: string example: x9Qk OIDCClaimMapping: type: object description: The ID token claims read for each attribute, by name. required: - email - email_verified - name - groups properties: email: type: string default: email example: email email_verified: type: string default: email_verified description: >- A boolean claim. Microsoft Entra ID does not send `email_verified`; map it to `xms_edov`. example: email_verified name: type: string default: name example: name groups: type: string default: groups example: groups Error: type: object required: - error properties: error: type: string description: A human-readable message. example: organization_id is required responses: BadRequest: description: >- Malformed request or failed validation. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: >- The organization's plan does not include this. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Authenticated but not allowed (permission, token scope, IP allowlist or CSRF). See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- Not found, or not visible to the caller. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- Conflicts with the current state. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: >- Well-formed but semantically invalid. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: token: type: http scheme: bearer bearerFormat: qumo_pat_ description: > A personal access token (`POST /v1/auth/tokens`) or a machine identity token (`POST /v1/projects/{project_id}/identities/{identity_id}/tokens`), both prefixed `qumo_pat_`. A token's scopes cap what it can do; see [Scopes and permissions](/guides/scopes-permissions). A personal token names no organization: on a route whose path names no project or organization, pass `?organization_id=`. cliSession: type: http scheme: bearer description: | The session token `qumod login` obtains through the device flow (`POST /v1/auth/device/token`). It acts as the signed-in user, like a console session, and needs no CSRF token. sessionCookie: type: apiKey in: cookie name: __Host-qumo_session description: | The console's browser session. Accepted only on the console origin (`https://console.qumo-deploy.com`), never on `api.qumo-deploy.com`. A request that changes state must also send `X-CSRF-Token`. csrfToken: type: apiKey in: header name: X-CSRF-Token description: | CSRF token paired with `sessionCookie` on POST, PUT, PATCH and DELETE. Bearer requests do not send it. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.