{
  "openapi": "3.0.3",
  "info": {
    "title": "Identity API",
    "version": "1.0.0",
    "description": "epilot as an OpenID Connect provider (\"Sign in with epilot\").\n\nThe standard OpenID Connect endpoints (discovery, JWKS, authorize, token, UserInfo, revocation)\nare described by the discovery document at `/.well-known/openid-configuration` and are not\nrepeated here. Partners integrate against that document with any certified OpenID Connect\nrelying-party library.\n\nThis specification covers the epilot-specific parts of the service:\n\n- the **operator API** used by epilot platform staff to register partner applications\n  (clients) and to enable organizations on them,\n- the **360 session endpoints** that let the portal prove a live 360 session during an\n  authorization (the session hop).\n\nTenant model: one confidential client per partner application and environment; the organization\na person is acting in travels in every ID token as the claim `https://id.epilot.cloud/claims/org_id`.\nA relying party must key everything on `(iss, sub, org_id)`.\n"
  },
  "tags": [
    {
      "name": "Operator Clients",
      "description": "Register and manage partner applications (OIDC clients). Platform operators only."
    },
    {
      "name": "Operator Organizations",
      "description": "Enable, suspend and revoke organizations on a partner client. Platform operators only."
    },
    {
      "name": "Session",
      "description": "360 session hop used by the epilot portal during an authorization."
    },
    {
      "name": "Launch",
      "description": "Start a partner login from an epilot link (OpenID Connect third-party initiated login)."
    }
  ],
  "servers": [
    {
      "url": "https://id.epilot.cloud"
    }
  ],
  "security": [
    {
      "OperatorAuth": []
    }
  ],
  "paths": {
    "/v1/identity/operator/clients": {
      "get": {
        "operationId": "listClients",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "listClients",
        "description": "List registered partner clients. The client secret is never returned.",
        "tags": [
          "Operator Clients"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PartnerKeyQuery"
          },
          {
            "$ref": "#/components/parameters/ClientStatusQuery"
          },
          {
            "$ref": "#/components/parameters/SizeQuery"
          },
          {
            "$ref": "#/components/parameters/CursorQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Clients",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClientList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "operationId": "createOidcClient",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "createOidcClient",
        "description": "Create a partner client in `draft` status. The client secret is returned exactly once in this\nresponse and can never be read again; use `rotateClientSecret` to obtain a new one.\n",
        "tags": [
          "Operator Clients"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerClientCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created client including its one-time secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClientWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        }
      ],
      "get": {
        "operationId": "getOidcClient",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "getOidcClient",
        "description": "Read a partner client. The client secret is never returned.",
        "tags": [
          "Operator Clients"
        ],
        "responses": {
          "200": {
            "description": "Client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClient"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "operationId": "updateClient",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "updateClient",
        "description": "Replace the mutable configuration of a client. `config_version` must equal the current\nversion (compare-and-swap); a mismatch is rejected with `409`.\n",
        "tags": [
          "Operator Clients"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerClientUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClient"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "delete": {
        "operationId": "retireClient",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "retireClient",
        "description": "Retire a client. The record is kept as a tombstone, the `client_id` is never reused, every\norganization enablement is revoked and all provider-side artefacts are revoked.\n",
        "tags": [
          "Operator Clients"
        ],
        "responses": {
          "200": {
            "description": "Retired client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClient"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}:activate": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        }
      ],
      "post": {
        "operationId": "activateClient",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "activateClient",
        "description": "Activate a `draft` or `suspended` client. Validates that every redirect URI is an absolute\nHTTPS URL without fragment, that `scopes_allowed` contains `openid`, and that the\nauthentication method is `client_secret_basic`.\n",
        "tags": [
          "Operator Clients"
        ],
        "responses": {
          "200": {
            "description": "Activated client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClient"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}:suspend": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        }
      ],
      "post": {
        "operationId": "suspendClient",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "suspendClient",
        "description": "Immediately block the client for every organization. Provider-side artefacts (codes, tokens,\ngrants) are revoked; the audit trail is kept. Reversible with `activateClient`.\n",
        "tags": [
          "Operator Clients"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suspended client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClient"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}:rotateSecret": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        }
      ],
      "post": {
        "operationId": "rotateClientSecret",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "rotateClientSecret",
        "description": "Issue a new client secret. The new secret is returned exactly once. The previous secret\nkeeps working until `previous_secret_expires_at` unless `compromise_mode` is set, in which\ncase it stops working immediately.\n",
        "tags": [
          "Operator Clients"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RotateSecretRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Client including its new one-time secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerClientWithSecret"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}/organizations": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        }
      ],
      "get": {
        "operationId": "listClientOrganizations",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "listClientOrganizations",
        "description": "List the organizations enabled on a client, including suspended and revoked ones.",
        "tags": [
          "Operator Organizations"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/OrgEnablementStatusQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization enablements",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablementList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "operationId": "enableClientOrganization",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "enableClientOrganization",
        "description": "Enable an epilot organization on a client, recording the customer's authorization policy\n(version 1). `allowed_scopes` must contain `openid` and be a subset of the client's\n`scopes_allowed`.\n",
        "tags": [
          "Operator Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgEnablementCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created enablement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}/organizations/{org_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        },
        {
          "$ref": "#/components/parameters/OrgIdPath"
        }
      ],
      "get": {
        "operationId": "getClientOrganization",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "getClientOrganization",
        "description": "Read one organization enablement.",
        "tags": [
          "Operator Organizations"
        ],
        "responses": {
          "200": {
            "description": "Enablement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablement"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "put": {
        "operationId": "updateClientOrganization",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "updateClientOrganization",
        "description": "Record a new version of the customer's authorization policy. `expected_policy_version` must\nequal the current version (compare-and-swap); a mismatch is rejected with `409`.\n",
        "tags": [
          "Operator Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgEnablementUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated enablement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablement"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      },
      "delete": {
        "operationId": "revokeClientOrganization",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "revokeClientOrganization",
        "description": "Revoke an organization's enablement. The record is kept as an audited tombstone; future\nauthorizations for this organization fail with `access_denied` and provider-side artefacts\nbound to it are revoked.\n",
        "tags": [
          "Operator Organizations"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked enablement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablement"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}/organizations/{org_id}:suspend": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        },
        {
          "$ref": "#/components/parameters/OrgIdPath"
        }
      ],
      "post": {
        "operationId": "suspendClientOrganization",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "suspendClientOrganization",
        "description": "Temporarily block one organization on this client. Reversible with `activateClientOrganization`.",
        "tags": [
          "Operator Organizations"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusChangeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suspended enablement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablement"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}/organizations/{org_id}:activate": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        },
        {
          "$ref": "#/components/parameters/OrgIdPath"
        }
      ],
      "post": {
        "operationId": "activateClientOrganization",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "activateClientOrganization",
        "description": "Resume a suspended organization on this client. Revoked enablements cannot be re-activated; enabling the organization again (`POST …/organizations`) replaces the revoked entry and continues its policy version.",
        "tags": [
          "Operator Organizations"
        ],
        "responses": {
          "200": {
            "description": "Active enablement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgEnablement"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/v1/identity/operator/clients/{client_id}/organizations/{org_id}/users/{user_id}:subject": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        },
        {
          "$ref": "#/components/parameters/OrgIdPath"
        },
        {
          "$ref": "#/components/parameters/UserIdPath"
        }
      ],
      "get": {
        "operationId": "getUserSubject",
        "x-epilot-permissions": [
          {
            "access": "internal"
          }
        ],
        "summary": "getUserSubject",
        "description": "The pairwise `sub` this client receives for one epilot user, so the partner can bind the person on its\nside **before** the first sign-in (for example a Babelforce agent provisioned through SCIM with\n`externalId = sub`).\n\nDerived exactly as the token endpoint derives it, never stored:\n`sub = key_version + \".\" + base64url(HMAC-SHA256(key[key_version], sector + \"\\n\" + user_id))`, where the\nsector is the client's `sector_identifier_uri` host or, without one, the host of its first redirect URI.\nThe same inputs always give the same value; it changes only when the client's sector or the active key\nversion changes.\n\nRequires an **active** client (a draft client's sector may still change and would invalidate every binding),\nan organization enablement that is not revoked, and the user being an active member of that organization\n(checked live against user-api). Every read is written to the audit trail: the value is a partner-facing\nidentifier.\n",
        "tags": [
          "Operator Organizations"
        ],
        "responses": {
          "200": {
            "description": "The subject this client sees for the user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserSubject"
                }
              }
            }
          },
          "400": {
            "description": "user_id is not the canonical epilot user id (the spelling 360 tokens carry)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Client, enablement or active organization membership not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Client not active, or the organization's enablement is revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/identity/session": {
      "get": {
        "operationId": "createIdentitySession",
        "x-epilot-permissions": [
          {
            "access": "self"
          }
        ],
        "summary": "createIdentitySession",
        "description": "Called by the epilot portal through the portal-host proxy after every persisted 360 session.\nValidates the 360 bearer token itself and mirrors it into the `identity_session` cookie\n(`HttpOnly; Secure; Path=/v1/identity`) whose lifetime is the remaining token lifetime, capped at 15 minutes\n(the portal mirrors the credential again on every token refresh and just before a partner sign-in).\nThe cookie is what proves the live 360 session during `completeInteraction`.\n",
        "tags": [
          "Session"
        ],
        "security": [
          {
            "EpilotAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Session mirrored into the cookie",
            "headers": {
              "Set-Cookie": {
                "description": "`identity_session=<360 ID token>; HttpOnly; Secure; SameSite=None; Path=/v1/identity; Max-Age=<remaining lifetime, at most 900>`",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdentitySession"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "delete": {
        "operationId": "deleteIdentitySession",
        "summary": "deleteIdentitySession",
        "description": "Clears the `identity_session` cookie. Called by the portal on logout.",
        "tags": [
          "Session"
        ],
        "security": [],
        "responses": {
          "204": {
            "description": "Cookie cleared",
            "headers": {
              "Set-Cookie": {
                "description": "Expired `identity_session` cookie",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/identity/interaction/{interaction_id}": {
      "parameters": [
        {
          "name": "interaction_id",
          "in": "path",
          "required": true,
          "description": "Opaque identifier of the parked authorization request",
          "schema": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      ]
    },
    "/v1/identity/launch/{client_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ClientIdPath"
        }
      ],
      "get": {
        "operationId": "launchClient",
        "summary": "launchClient",
        "description": "One validated place for partner start links (manager UI, hosted apps). Redirects the browser to the\nclient's registered `initiate_login_uri` with `iss` set to this issuer and, when given, the deep link as\n`target_link_uri` (OpenID Connect Core §4, third-party initiated login). Authenticates nobody: the partner\nthen starts a normal \"Sign in with epilot\" authorization.\n\n`target` must be an absolute HTTPS URL starting with one of the client's registered\n`launch_target_prefixes`; anything else is rejected. Retired, suspended or draft clients, and clients\nwithout an `initiate_login_uri`, answer `404`.\n",
        "tags": [
          "Launch"
        ],
        "security": [],
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "required": false,
            "description": "Deep link inside the partner application to continue to after login",
            "schema": {
              "type": "string",
              "format": "uri",
              "maxLength": 2048
            }
          },
          {
            "$ref": "#/components/parameters/AnyOtherQueryParameters"
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to the partner's initiate_login_uri",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OperatorAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Internal-auth bearer token minted for an epilot admin-portal user. Customer organization\nbearers are never accepted; the caller must belong to an allowed admin-portal group.\n"
      },
      "EpilotAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Authorization header with the caller's epilot 360 bearer token."
      },
      "IdentitySessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "identity_session",
        "description": "Cookie set by `createIdentitySession`, carrying the live 360 credential."
      }
    },
    "parameters": {
      "AnyOtherQueryParameters": {
        "name": "extra",
        "in": "query",
        "required": false,
        "description": "Any other query parameters (marketing tags on a start link, parameters a proxy appends) are accepted\nand ignored. Start links and the session hop must never fail on an unknown parameter.\n",
        "style": "form",
        "explode": true,
        "schema": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "ClientIdPath": {
        "name": "client_id",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/PartnerClientId"
        }
      },
      "OrgIdPath": {
        "name": "org_id",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/OrgId"
        }
      },
      "UserIdPath": {
        "name": "user_id",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/UserId"
        }
      },
      "PartnerKeyQuery": {
        "name": "partner_key",
        "in": "query",
        "required": false,
        "description": "Filter by partner key",
        "schema": {
          "type": "string"
        }
      },
      "ClientStatusQuery": {
        "name": "status",
        "in": "query",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/PartnerClientStatus"
        }
      },
      "OrgEnablementStatusQuery": {
        "name": "status",
        "in": "query",
        "required": false,
        "schema": {
          "$ref": "#/components/schemas/OrgEnablementStatus"
        }
      },
      "SizeQuery": {
        "name": "size",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        }
      },
      "CursorQuery": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "Opaque cursor from a previous response",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid credentials",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Caller is not a platform operator",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "Version mismatch or invalid state transition",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "integer",
            "example": 404
          },
          "error": {
            "type": "string",
            "example": "Client not found"
          },
          "details": {
            "type": "array",
            "description": "Request validation problems (only on `400` from schema validation)",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "PartnerClientId": {
        "type": "string",
        "description": "Opaque client identifier, unique within the issuer, never reused",
        "example": "bf-prod-x7k2",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._~-]+$"
      },
      "OrgId": {
        "type": "string",
        "description": "epilot organization id, an opaque case-sensitive string",
        "example": "739224",
        "minLength": 1,
        "maxLength": 64,
        "pattern": "^[A-Za-z0-9_-]+$"
      },
      "UserId": {
        "type": "string",
        "description": "epilot user id (`custom:ivy_user_id` in a 360 token). A user belongs to exactly one organization.",
        "example": "100321",
        "minLength": 1,
        "maxLength": 64,
        "pattern": "^[A-Za-z0-9_-]+$"
      },
      "Environment": {
        "type": "string",
        "description": "Partner-side environment this client belongs to",
        "enum": [
          "dev",
          "staging",
          "production"
        ]
      },
      "PartnerClientStatus": {
        "type": "string",
        "enum": [
          "draft",
          "active",
          "suspended",
          "retired"
        ]
      },
      "Scope": {
        "type": "string",
        "enum": [
          "openid",
          "email",
          "profile"
        ]
      },
      "HttpsUri": {
        "type": "string",
        "format": "uri",
        "description": "Absolute HTTPS URL without fragment",
        "example": "https://partner.example.com/auth/callback"
      },
      "PartnerClientCreate": {
        "type": "object",
        "required": [
          "partner_key",
          "display_name",
          "environment",
          "redirect_uris"
        ],
        "properties": {
          "partner_key": {
            "type": "string",
            "description": "Stable key of the partner application, shared by its environments",
            "example": "babelforce",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-z0-9][a-z0-9-]*$"
          },
          "display_name": {
            "type": "string",
            "example": "Babelforce",
            "minLength": 1,
            "maxLength": 128
          },
          "description": {
            "type": "string",
            "maxLength": 1024
          },
          "environment": {
            "$ref": "#/components/schemas/Environment"
          },
          "redirect_uris": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/HttpsUri"
            }
          },
          "sector_identifier_uri": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HttpsUri"
              }
            ],
            "description": "Optional. Pairwise sector for `sub` derivation. Required when the redirect URIs span\nmore than one host, so one person keeps one `sub` at this partner.\n"
          },
          "initiate_login_uri": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HttpsUri"
              }
            ],
            "description": "Where a login started from epilot should begin at the partner"
          },
          "launch_target_prefixes": {
            "type": "array",
            "description": "Allowed prefixes for deep-link targets when a login is started from epilot",
            "items": {
              "type": "string"
            }
          },
          "scopes_allowed": {
            "type": "array",
            "description": "Upper bound for every organization enablement's `allowed_scopes`. Defaults to all scopes.",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          }
        }
      },
      "PartnerClientUpdate": {
        "type": "object",
        "required": [
          "config_version",
          "display_name",
          "redirect_uris",
          "scopes_allowed"
        ],
        "properties": {
          "config_version": {
            "type": "integer",
            "description": "Current configuration version, for compare-and-swap",
            "minimum": 1
          },
          "allow_sector_change": {
            "type": "boolean",
            "default": false,
            "description": "Required (true) when the update changes the pairwise sector of an **active** client, i.e. the\n`sector_identifier_uri` host or, without one, the redirect host. Changing the sector changes the\n`sub` of every person at this partner; without this flag such an update is rejected with `409`.\n"
          },
          "display_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "description": {
            "type": "string",
            "maxLength": 1024
          },
          "redirect_uris": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/HttpsUri"
            }
          },
          "sector_identifier_uri": {
            "$ref": "#/components/schemas/HttpsUri"
          },
          "initiate_login_uri": {
            "$ref": "#/components/schemas/HttpsUri"
          },
          "launch_target_prefixes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scopes_allowed": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          }
        }
      },
      "PartnerClient": {
        "type": "object",
        "required": [
          "client_id",
          "partner_key",
          "display_name",
          "environment",
          "redirect_uris",
          "token_endpoint_auth_method",
          "grant_types",
          "scopes_allowed",
          "status",
          "config_version",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "client_id": {
            "$ref": "#/components/schemas/PartnerClientId"
          },
          "partner_key": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "environment": {
            "$ref": "#/components/schemas/Environment"
          },
          "redirect_uris": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HttpsUri"
            }
          },
          "sector_identifier_uri": {
            "$ref": "#/components/schemas/HttpsUri"
          },
          "initiate_login_uri": {
            "$ref": "#/components/schemas/HttpsUri"
          },
          "launch_target_prefixes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "token_endpoint_auth_method": {
            "type": "string",
            "enum": [
              "client_secret_basic"
            ]
          },
          "grant_types": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "authorization_code"
              ]
            }
          },
          "scopes_allowed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "status": {
            "$ref": "#/components/schemas/PartnerClientStatus"
          },
          "status_reason": {
            "type": "string",
            "description": "Operator-supplied reason for the last suspension or retirement"
          },
          "config_version": {
            "type": "integer",
            "minimum": 1
          },
          "secret_rotated_at": {
            "type": "string",
            "format": "date-time"
          },
          "previous_secret_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Until when the previous secret still authenticates after a rotation"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_by": {
            "type": "string",
            "description": "Email of the admin-portal operator who created the client (their Cognito identity when the pool holds no email)"
          },
          "updated_by": {
            "type": "string",
            "description": "Email of the admin-portal operator who last changed the client"
          }
        }
      },
      "PartnerClientWithSecret": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PartnerClient"
          },
          {
            "type": "object",
            "required": [
              "client_secret"
            ],
            "properties": {
              "client_secret": {
                "type": "string",
                "description": "Returned exactly once. Store it securely; it cannot be retrieved again."
              }
            }
          }
        ]
      },
      "PartnerClientList": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerClient"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "StatusChangeRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 1024
          }
        }
      },
      "RotateSecretRequest": {
        "type": "object",
        "properties": {
          "compromise_mode": {
            "type": "boolean",
            "default": false,
            "description": "When true the previous secret stops working immediately"
          },
          "migration_window_seconds": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2592000,
            "default": 86400,
            "description": "How long the previous secret keeps working (ignored in compromise mode)"
          }
        }
      },
      "AuthorizationPolicyInput": {
        "type": "object",
        "required": [
          "allowed_scopes",
          "customer_approval_ref"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "preauthorized"
            ],
            "default": "preauthorized"
          },
          "population": {
            "type": "string",
            "enum": [
              "all_current_org_members"
            ],
            "default": "all_current_org_members"
          },
          "allowed_scopes": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "description": "Must contain `openid` and be a subset of the client's `scopes_allowed`",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          },
          "customer_approval_ref": {
            "type": "string",
            "description": "Reference to the customer's approval evidence (ticket, signed order, contract clause)",
            "minLength": 1,
            "maxLength": 512
          },
          "approved_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer approved. Optional: enabling an organization defaults it to the time of the\nrequest, and a policy update keeps the current value unless a new one is given.\n"
          }
        }
      },
      "AuthorizationPolicy": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuthorizationPolicyInput"
          },
          {
            "type": "object",
            "required": [
              "approved_at",
              "version",
              "mandatory_claims",
              "recorded_by",
              "recorded_at"
            ],
            "properties": {
              "approved_at": {
                "type": "string",
                "format": "date-time"
              },
              "version": {
                "type": "integer",
                "minimum": 1
              },
              "mandatory_claims": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "org_id"
                  ]
                }
              },
              "recorded_by": {
                "type": "string",
                "description": "Email of the admin-portal operator who recorded this policy version"
              },
              "recorded_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        ]
      },
      "OrgEnablementStatus": {
        "type": "string",
        "enum": [
          "active",
          "suspended",
          "revoked"
        ]
      },
      "OrgEnablementCreate": {
        "type": "object",
        "required": [
          "org_id",
          "authorization_policy"
        ],
        "properties": {
          "org_id": {
            "$ref": "#/components/schemas/OrgId"
          },
          "authorization_policy": {
            "$ref": "#/components/schemas/AuthorizationPolicyInput"
          }
        }
      },
      "OrgEnablementUpdate": {
        "type": "object",
        "required": [
          "expected_policy_version",
          "authorization_policy"
        ],
        "properties": {
          "expected_policy_version": {
            "type": "integer",
            "minimum": 1,
            "description": "Current policy version, for compare-and-swap"
          },
          "authorization_policy": {
            "$ref": "#/components/schemas/AuthorizationPolicyInput"
          }
        }
      },
      "OrgEnablement": {
        "type": "object",
        "required": [
          "client_id",
          "org_id",
          "status",
          "authorization_policy",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "client_id": {
            "$ref": "#/components/schemas/PartnerClientId"
          },
          "org_id": {
            "$ref": "#/components/schemas/OrgId"
          },
          "status": {
            "$ref": "#/components/schemas/OrgEnablementStatus"
          },
          "status_reason": {
            "type": "string"
          },
          "authorization_policy": {
            "$ref": "#/components/schemas/AuthorizationPolicy"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_by": {
            "type": "string",
            "description": "Email of the admin-portal operator who enabled the organization"
          },
          "updated_by": {
            "type": "string",
            "description": "Email of the admin-portal operator who last changed the enablement"
          }
        }
      },
      "OrgEnablementList": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrgEnablement"
            }
          }
        }
      },
      "IdentitySession": {
        "type": "object",
        "required": [
          "org_id",
          "user_id",
          "expires_at"
        ],
        "properties": {
          "org_id": {
            "$ref": "#/components/schemas/OrgId"
          },
          "user_id": {
            "type": "string",
            "description": "epilot user id of the session owner"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the cookie expires (the mirrored credential's expiry, capped at 15 minutes)"
          }
        }
      },
      "UserSubject": {
        "type": "object",
        "required": [
          "client_id",
          "org_id",
          "user_id",
          "sub",
          "key_version",
          "sector"
        ],
        "properties": {
          "client_id": {
            "$ref": "#/components/schemas/PartnerClientId"
          },
          "org_id": {
            "$ref": "#/components/schemas/OrgId"
          },
          "user_id": {
            "$ref": "#/components/schemas/UserId"
          },
          "sub": {
            "type": "string",
            "description": "The pairwise subject this client receives for the user, `<key_version>.<base64url digest>`",
            "example": "v1.dGhpcy1pcy1hLWR1bW15LXN1YmplY3QtdmFsdWUtMDAx"
          },
          "key_version": {
            "type": "string",
            "description": "Active pairwise key version the value was derived with",
            "example": "v1"
          },
          "sector": {
            "type": "string",
            "description": "Pairwise sector the value was derived for (sector_identifier_uri host, else the first redirect host)",
            "example": "portal.epilot.cloud"
          }
        }
      }
    }
  }
}
