openapi: 3.1.0
info:
  title: Teamusers API
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Nekostick /iam Strip forwarding
tags:
  - Audit
  - Authentication
  - Authorization
  - Bindings
  - Groups
  - Health
  - Impersonation
  - Invitations
  - Keys
  - Permissions
  - Policies
  - Roles
  - SCIM
  - Self-service
  - Sessions
  - Teams
  - Users
paths:
  /.well-known/jwks.json:
    get:
      tags:
        - Authentication
      summary: Fetch public signing keys
      description: Use this public endpoint to validate teamusers EdDSA JWT signatures locally. API gateways and services call it and cache the returned key set by kid.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                keys:
                  - alg: EdDSA
                    crv: Ed25519
                    kid: 01J8Z3KEY00000000000000001
                    kty: OKP
                    use: sig
                    x: 11qYAYL9f3rK3z7Z4Yj6d8bYJQ4mC3bX2h0qk8mVqB8
        "500":
          description: Signing key set could not be encoded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Signing key set could not be encoded
                status: 500
                detail: jwks unavailable
      security: []
  /audit/:
    get:
      tags:
        - Audit
      summary: List audit entries
      description: Use for compliance review and incident investigation. Audit rows are append-only while retained; retention defaults to keep forever and an optional `team_id` filter is supported. Results are ordered by ascending numeric audit ID. The `cursor` is a non-negative decimal string ID (omit, leave empty, or use `0` for the first page); IDs remain numeric in `items`. See [REST pagination](/guide/pagination) for the shared limit, envelope, and terminal-cursor contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        action:
                          type: string
                        actor_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        at:
                          format: date-time
                          type: string
                        diff: true
                        id:
                          type: integer
                        request_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        target:
                          type: string
                        team_id:
                          anyOf:
                            - type: string
                            - type: "null"
                      required:
                        - id
                        - action
                        - target
                        - diff
                        - at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - action: user.created
                    actor_id: 01J8Z3ADMIN000000000000001
                    at: "2026-01-01T00:00:00Z"
                    diff:
                      status: active
                    id: 1
                    request_id: req-01J8Z3
                    target: 01J8Z3USER000000000000001
                    team_id: 01J8Z3TEAM000000000000001
                next_cursor: ""
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                cursor must be a non-negative integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: cursor must be a non-negative integer
                limit must be a positive integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:audit:any
  /audit/export:
    get:
      tags:
        - Audit
      summary: Export audit entries
      description: Stream matching audit rows as JSON Lines (one row per line, the default) or CSV. The optional team_id filter matches GET /audit; export scans all matching rows and does not use cursor pagination.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                items:
                  properties:
                    action:
                      type: string
                    actor_id:
                      anyOf:
                        - type: string
                        - type: "null"
                    at:
                      format: date-time
                      type: string
                    diff: true
                    id:
                      type: integer
                    request_id:
                      anyOf:
                        - type: string
                        - type: "null"
                    target:
                      type: string
                    team_id:
                      anyOf:
                        - type: string
                        - type: "null"
                  required:
                    - id
                    - action
                    - target
                    - diff
                    - at
                  type: object
                type: array
              example:
                - action: user.created
                  actor_id: 01J8Z3ADMIN000000000000001
                  at: "2026-01-01T00:00:00Z"
                  diff:
                    status: active
                  id: 1
                  request_id: req-01J8Z3
                  target: 01J8Z3USER000000000000001
                  team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: format must be jsonl or csv
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:audit:any
  /auth/client-credentials:
    post:
      tags:
        - Authentication
      summary: Obtain a service token
      description: Use for service-to-service authentication. The caller presents the client ID (service user's username) and one-time secret created by POST /users/{id}/credentials with kind service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
              required:
                - client_id
                - client_secret
              type: object
            example:
              client_id: orders-service
              client_secret: generated-service-secret
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                required:
                  - access_token
                  - refresh_token
                  - token_type
                  - expires_in
                type: object
              example:
                access_token: eyJhbGciOiJFZERTQSIs...
                expires_in: 600
                refresh_token: refresh-token-opaque
                token_type: Bearer
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/introspect:
    post:
      tags:
        - Authentication
      summary: Introspect an access or refresh token
      description: Use from a trusted service to check whether a token is active without exposing token material. The caller must authenticate with a service-kind EdDSA bearer token; inactive or missing input still returns 200 with active false.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                token:
                  type: string
              type: object
            example:
              token: eyJhbGciOiJFZERTQSIs...
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  act:
                    additionalProperties:
                      type: string
                    type: object
                  active:
                    type: boolean
                  exp:
                    type: integer
                  imp:
                    type: boolean
                  kind:
                    type: string
                  perm_ver:
                    type: integer
                  sub:
                    type: string
                  team:
                    type: string
                required:
                  - active
                type: object
              example:
                active: true
                exp: 1760000000
                kind: user
                perm_ver: 3
                sub: 01J8Z3USER000000000000001
                team: 01J8Z3TEAM000000000000001
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /auth/invite/accept:
    post:
      tags:
        - Authentication
      summary: Accept an invitation
      description: Use from an invitation email to set the initial password and activate the invited account. The invitation email is marked verified; display_name is optional.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                password:
                  type: string
                token:
                  type: string
              required:
                - token
                - password
              type: object
            example:
              display_name: Alice Example
              password: NewAtLeastTwelve1
              token: invitation-token-from-email
      responses:
        "204":
          description: No Content
        "400":
          description: invalid_token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_token
                status: 400
                detail: invalid_token
        "422":
          description: weak_password
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: weak_password
                status: 422
                detail: weak_password
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/login:
    post:
      tags:
        - Authentication
      summary: Sign in with a password
      description: Use when an end user needs an access and refresh token pair. Administrator-provisioned passwords instead return 403 password_change_required with a ten-minute change_token accepted only by POST /me/password; that endpoint still verifies the current password. Accounts with TOTP enabled or an effective required-MFA policy receive an initial MFA challenge, or a restricted MFA-enrollment token when required TOTP is not enrolled. Complete this login challenge at POST /auth/login/mfa; it is distinct from authenticated MFA-only step-up. Access tokens carry auth_time for primary authentication and may carry step_up_time only after POST /auth/step-up/complete; refresh preserves both.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                password:
                  type: string
                username:
                  type: string
              required:
                - username
                - password
              type: object
            example:
              password: AtLeastTwelve1
              username: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  mfa_enrollment_required:
                    type: boolean
                  mfa_methods:
                    items:
                      type: string
                    type: array
                  mfa_required:
                    type: boolean
                  mfa_token:
                    type: string
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                type: object
              example:
                mfa_methods:
                  - otp
                mfa_required: true
                mfa_token: eyJhbGciOiJFZERTQSIs...
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: account_pending; password_change_required; mfa_enrollment_denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                account_pending:
                  value:
                    type: about:blank
                    title: account_pending
                    status: 403
                    detail: account_pending
                password_change_required:
                  value:
                    type: about:blank
                    title: password_change_required
                    status: 403
                    detail: password_change_required
                mfa_enrollment_denied:
                  value:
                    type: about:blank
                    title: mfa_enrollment_denied
                    status: 403
                    detail: mfa_enrollment_denied
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/login/mfa:
    post:
      tags:
        - Authentication
      summary: Complete MFA login
      description: Use after password or passkey login returns mfa_required. Submit the short-lived MFA token and either a current TOTP code or one unused backup code. This completes initial login MFA, not MFA-only step-up; success returns the normal token pair with the primary-auth auth_time unchanged and additive amr claims.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                code:
                  type: string
                mfa_token:
                  type: string
              required:
                - mfa_token
                - code
              type: object
            example:
              code: "123456"
              mfa_token: eyJhbGciOiJFZERTQSIs...
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                required:
                  - access_token
                  - refresh_token
                  - token_type
                  - expires_in
                type: object
              example:
                access_token: eyJhbGciOiJFZERTQSIs...
                expires_in: 600
                refresh_token: refresh-token-opaque
                token_type: Bearer
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/login/mfa/enroll/begin:
    post:
      tags:
        - Authentication
      summary: Begin required MFA enrollment
      description: Use with the restricted mfa_token returned as mfa_enrollment_required when required TOTP is not enrolled. It authorizes only initial-login enrollment and returns a pending TOTP secret; it is not an access token. MFA-only step-up never enrolls a factor.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                code:
                  type: string
                mfa_token:
                  type: string
              required:
                - mfa_token
              type: object
            example:
              mfa_token: eyJhbGciOiJFZERTQSIs...
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  otpauth_url:
                    type: string
                  secret:
                    type: string
                required:
                  - secret
                  - otpauth_url
                type: object
              example:
                otpauth_url: otpauth://totp/teamusers:alice?secret=JBSWY3DPEHPK3PXP&issuer=teamusers
                secret: JBSWY3DPEHPK3PXP
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "409":
          description: totp_already_enabled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: totp_already_enabled
                status: 409
                detail: totp_already_enabled
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/login/mfa/enroll/complete:
    post:
      tags:
        - Authentication
      summary: Complete required MFA enrollment
      description: Use after beginning required TOTP enrollment with the same restricted mfa_token. A valid code activates TOTP and returns backup codes with a full token pair whose amr includes otp and whose auth_time remains the primary authentication time. This initial enrollment flow is distinct from MFA-only step-up.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                code:
                  type: string
                mfa_token:
                  type: string
              required:
                - mfa_token
              type: object
            example:
              code: "123456"
              mfa_token: eyJhbGciOiJFZERTQSIs...
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  backup_codes:
                    items:
                      type: string
                    type: array
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                required:
                  - access_token
                  - refresh_token
                  - token_type
                  - expires_in
                  - backup_codes
                type: object
              example:
                access_token: eyJhbGciOiJFZERTQSIs...
                backup_codes:
                  - abcd1234efgh5678
                expires_in: 600
                refresh_token: refresh-token-opaque
                token_type: Bearer
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "409":
          description: totp_already_enabled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: totp_already_enabled
                status: 409
                detail: totp_already_enabled
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/logout:
    post:
      tags:
        - Authentication
      summary: Revoke a refresh-token family
      description: 'Use when a client signs out. The operation is intentionally idempotent: missing, malformed, unknown, expired, or already-revoked refresh tokens produce 204 and do not disclose token state.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                refresh_token:
                  type: string
              required:
                - refresh_token
              type: object
            example:
              refresh_token: refresh-token-opaque
      responses:
        "204":
          description: No Content
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/oidc/begin:
    get:
      tags:
        - Authentication
      summary: Begin OIDC login
      description: When OIDC is configured, redirects to the configured issuer with single-use state, nonce, and PKCE S256 challenge. The state and nonce digests, challenge, and verifier are stored server-side for five minutes. The endpoint sets a Secure, HttpOnly, SameSite=Lax __Host-oidc_state cookie containing the state digest, with Path=/ and no Domain; Secure is unconditional because TLS terminates at the trusted proxy. The endpoint is rate-limited and responds with an HTTP 302 Location header rather than a JSON body.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
        "404":
          description: OIDC Not Configured
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: OIDC Not Configured
                status: 404
                detail: oidc_not_configured
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/oidc/callback:
    get:
      tags:
        - Authentication
      summary: Complete OIDC login
      description: Requires a matching state-digest cookie, consumes state once, and exchanges the authorization code with its PKCE verifier using a ten-second timeout. Verifies the signed ID token against cached issuer JWKS and validates issuer, audience, expiry, iat, nbf, and nonce; iat cannot be older than ten minutes or more than 30 seconds in the future, and nbf cannot be more than 30 seconds in the future. An unknown kid triggers a JWKS refresh. Email linking requires a locally verified email on a user that is not pending or invited; erased accounts are not linkable. Refused links return 403 oidc_link_refused. Returns a JSON token pair, or an initial MFA challenge after OIDC primary authentication when local MFA is required; it never redirects to a frontend.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  mfa_enrollment_required:
                    type: boolean
                  mfa_methods:
                    items:
                      type: string
                    type: array
                  mfa_required:
                    type: boolean
                  mfa_token:
                    type: string
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                type: object
              example:
                access_token: signed-access-token
                expires_in: 600
                refresh_token: opaque-refresh-token
                token_type: Bearer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: oidc_link_refused; registration_closed; account_pending; mfa_enrollment_denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                oidc_link_refused:
                  value:
                    type: about:blank
                    title: oidc_link_refused
                    status: 403
                    detail: oidc_link_refused
                registration_closed:
                  value:
                    type: about:blank
                    title: registration_closed
                    status: 403
                    detail: registration_closed
                account_pending:
                  value:
                    type: about:blank
                    title: account_pending
                    status: 403
                    detail: account_pending
                mfa_enrollment_denied:
                  value:
                    type: about:blank
                    title: mfa_enrollment_denied
                    status: 403
                    detail: mfa_enrollment_denied
        "404":
          description: OIDC Not Configured
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: OIDC Not Configured
                status: 404
                detail: oidc_not_configured
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/passkey/login/begin:
    post:
      tags:
        - Authentication
      summary: Begin passkey login
      description: Use to begin a WebAuthn assertion. Pass an optional username for a scoped ceremony, or an empty body for discoverable credentials; the browser passes the returned publicKey options to navigator.credentials.get.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
              type: object
            example:
              username: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                publicKey:
                  allowCredentials:
                    - id: base64url-credential-id
                      type: public-key
                  challenge: base64url-challenge
                  rpId: localhost
                  timeout: 300000
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/passkey/login/finish:
    post:
      tags:
        - Authentication
      summary: Finish passkey login
      description: Use with the browser's PublicKeyCredential assertion response from the begin operation. A userVerified assertion can satisfy required MFA at primary login; this is separate from MFA-only step-up. Without user verification, enrolled TOTP triggers an initial MFA challenge; when TOTP is not enrolled, a required MFA policy yields a restricted enrollment token or, when deny_unenrolled is set, a 403 mfa_enrollment_denied. Without either TOTP or a required policy, login returns a full token pair. Successful access tokens include amr and primary-auth auth_time; only the separate step-up flow sets step_up_time.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
            example:
              id: base64url-credential-id
              rawId: base64url-credential-id
              response:
                authenticatorData: base64url-authenticator-data
                clientDataJSON: base64url-client-data
                signature: base64url-signature
              type: public-key
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  mfa_enrollment_required:
                    type: boolean
                  mfa_methods:
                    items:
                      type: string
                    type: array
                  mfa_required:
                    type: boolean
                  mfa_token:
                    type: string
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                type: object
              example:
                mfa_methods:
                  - otp
                mfa_required: true
                mfa_token: eyJhbGciOiJFZERTQSIs...
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid WebAuthn response
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: mfa_enrollment_denied
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: mfa_enrollment_denied
                status: 403
                detail: mfa_enrollment_denied
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/password-reset/confirm:
    post:
      tags:
        - Authentication
      summary: Confirm a password reset
      description: Use with the one-time token delivered by the notification service. The new password must satisfy policy; success revokes all sessions and clears lockout state.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                new_password:
                  type: string
                token:
                  type: string
              required:
                - token
                - new_password
              type: object
            example:
              new_password: NewAtLeastTwelve1
              token: reset-token-from-email
      responses:
        "204":
          description: No Content
        "400":
          description: invalid_token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_token
                status: 400
                detail: invalid_token
        "422":
          description: weak_password
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: weak_password
                status: 422
                detail: weak_password
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/password-reset/request:
    post:
      tags:
        - Authentication
      summary: Request a password reset
      description: Use when a user has lost a password. Submit a username or email; the endpoint always returns 204 so callers cannot enumerate accounts. A notification event is emitted only for an active matching account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                login:
                  type: string
              required:
                - login
              type: object
            example:
              login: alice@example.test
      responses:
        "204":
          description: No Content
      security: []
  /auth/refresh:
    post:
      tags:
        - Authentication
      summary: Rotate a refresh token
      description: Use to obtain a fresh access/refresh pair without prompting the user for a password. Rotation revokes the presented token and stays within the same session family and original family_not_after cap. It preserves the primary-auth auth_time and any step_up_time unchanged; refresh never makes authentication fresh. Reuse or expiry invalidates the request and can revoke its whole family.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                refresh_token:
                  type: string
              required:
                - refresh_token
              type: object
            example:
              refresh_token: refresh-token-opaque
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                required:
                  - access_token
                  - refresh_token
                  - token_type
                  - expires_in
                type: object
              example:
                access_token: eyJhbGciOiJFZERTQSIs...
                expires_in: 600
                refresh_token: refresh-token-rotated
                token_type: Bearer
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/register:
    post:
      tags:
        - Authentication
      summary: Register a user
      description: Use for public self-registration when registration mode is open or approval. A web or mobile client submits the profile and password; the service creates a pending account and sends an email verification notification. Closed mode rejects registration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                display_name:
                  type: string
                email:
                  type: string
                password:
                  type: string
                username:
                  type: string
              required:
                - username
                - email
                - password
              type: object
            example:
              display_name: Alice Example
              email: alice@example.test
              password: AtLeastTwelve1
              username: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
              example:
                id: 01J8Z3USER000000000000001
                status: pending
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "403":
          description: registration_closed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: registration_closed
                status: 403
                detail: registration_closed
        "422":
          description: weak_password
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: weak_password
                status: 422
                detail: weak_password
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /auth/step-up/begin:
    post:
      tags:
        - Authentication
      summary: Begin MFA-only step-up
      description: 'Use with an authenticated user bearer and its current refresh token after a guarded operation returns 403 step_up_required; this route is not freshness-guarded. The refresh token binds a persisted, purpose-specific, single-use challenge to the same user and session, and the step_up_token expires after five minutes. methods lists only currently enrolled, usable factors: otp for TOTP, backup_code for an unused backup code, and webauthn for a passkey. When webauthn is available, public_key is the direct user-bound assertion-options object with challenge, timeout, rpId, allowCredentials, and userVerification set to required (plus optional library extensions). This flow never enrolls a factor. Service and impersonation tokens return 403 step_up_forbidden; if no eligible factor is available, begin returns 403 step_up_not_available and the user must complete full primary login and any required enrollment instead. Accepts Idempotency-Key; the same key and body in the same raw Authorization scope replay the response, while a changed bearer uses a different scope. If canceled, abandon the challenge and let it expire.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                refresh_token:
                  type: string
              required:
                - refresh_token
              type: object
            example:
              refresh_token: <current refresh token for this user bearer>
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  expires_in:
                    type: integer
                  methods:
                    items:
                      type: string
                    type: array
                  public_key:
                    additionalProperties: true
                    type: object
                  step_up_token:
                    type: string
                required:
                  - step_up_token
                  - methods
                  - expires_in
                type: object
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                request body must be valid JSON:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: request body must be valid JSON
                refresh_token is required:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: refresh_token is required
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: step_up_forbidden; step_up_not_available
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                step_up_forbidden:
                  value:
                    type: about:blank
                    title: step_up_forbidden
                    status: 403
                    detail: step_up_forbidden
                step_up_not_available:
                  value:
                    type: about:blank
                    title: step_up_not_available
                    status: 403
                    detail: step_up_not_available
        "409":
          description: Idempotency In Progress
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency In Progress
                status: 409
                detail: idempotency_in_progress
        "422":
          description: Idempotency Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency Conflict
                status: 422
                detail: idempotency_conflict
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /auth/step-up/complete:
    post:
      tags:
        - Authentication
      summary: Complete MFA-only step-up
      description: 'Use the step_up_token and same current refresh token supplied to POST /auth/step-up/begin, plus exactly one proof: code for TOTP or an unused backup code, or credential for the user-verified WebAuthn assertion serialized from navigator.credentials.get using the begin response''s public_key options. The authenticated user bearer and challenge must match the refresh session. A valid proof atomically consumes the one-use challenge and proof, rotates the refresh token within the original session family without extending family_not_after, preserves primary-auth auth_time and amr, and adds step_up_time; normal refresh preserves both timestamps without making them newer. Failed factor proofs return 401 authentication failed without consuming the persisted challenge, proof, or refresh session, subject to rate limits and account lockout. step_up_not_available is begin-only. Replace both stored tokens only after success. Accepts Idempotency-Key: use a new key for a different proof because a same-key/same-body retry replays the prior response and the same key with a different body conflicts; a changed bearer uses a different raw Authorization scope. After an ambiguous network failure, do not automatically retry. If canceled, abandon the challenge and let it expire.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                code:
                  type: string
                credential: true
                refresh_token:
                  type: string
                step_up_token:
                  type: string
              required:
                - refresh_token
                - step_up_token
              type: object
            example:
              code: "123456"
              refresh_token: <current refresh token for this user bearer>
              step_up_token: <step_up_token returned by begin>
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                required:
                  - access_token
                  - refresh_token
                  - token_type
                  - expires_in
                type: object
        "400":
          description: Invalid Request; Invalid Request; Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                request body must be valid JSON:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: request body must be valid JSON
                refresh_token and step_up_token are required:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: refresh_token and step_up_token are required
                exactly one of code or credential is required:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: exactly one of code or credential is required
                invalid WebAuthn response:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: invalid WebAuthn response
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: step_up_forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: step_up_forbidden
                status: 403
                detail: step_up_forbidden
        "409":
          description: Idempotency In Progress
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency In Progress
                status: 409
                detail: idempotency_in_progress
        "422":
          description: Idempotency Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency Conflict
                status: 422
                detail: idempotency_conflict
        "423":
          description: account_locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: account_locked
                status: 423
                detail: account_locked
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /auth/verify-email:
    post:
      tags:
        - Authentication
      summary: Verify an email address
      description: Use from the link or token delivered by the notification service after registration. It marks the account verified and, in open mode, activates it; approval mode still requires administrator approval.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                token:
                  type: string
              required:
                - token
              type: object
            example:
              token: verification-token-from-email
      responses:
        "204":
          description: No Content
        "400":
          description: invalid_token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_token
                status: 400
                detail: invalid_token
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security: []
  /authz/check:
    post:
      tags:
        - Authorization
      summary: Evaluate a permission
      description: Use from a trusted application service to make a single authorization decision for a user and resource context. The caller must use a service-kind bearer token. Every non-platform (team-scoped) grant applies only to its matching active resource.team_id; team baselines are inherited by users with any unexpired group membership in that active team. Platform bindings with null team_id remain available without team membership, but an eligible member's applicable team deny still overrides a matching platform allow for that team's resource. A platform administrator without active membership does not inherit the baseline deny and retains independent platform grants. A requested :team permission without resource.team_id denies. A false condition excludes only that grant and, if nothing else matches, leaves reason no matching grant; an error evaluating any applicable condition fails the whole decision with reason condition_error. Explicit deny wins matching allows; there is no role/source priority. matched lists every applicable key that matched, sorted lexicographically. Set max_auth_age_seconds to require recent authentication and pass auth_time from the user's token; a missing, future, or stale auth_time returns allow=false with reason step_up_required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                auth_time:
                  type: integer
                context:
                  properties:
                    resource:
                      properties:
                        attrs:
                          additionalProperties: true
                          type: object
                        owner_id:
                          type: string
                        team_id:
                          type: string
                      type: object
                  type: object
                max_auth_age_seconds:
                  type: integer
                permission:
                  type: string
                subject:
                  type: string
              required:
                - subject
                - permission
              type: object
            example:
              auth_time: 1727712000
              context:
                resource:
                  attrs:
                    region: us-east-1
                  owner_id: 01J8Z3OWNER000000000000001
                  team_id: 01J8Z3TEAM000000000000001
              max_auth_age_seconds: 600
              permission: orders:read:team
              subject: 01J8Z3USER000000000000001
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  allow:
                    type: boolean
                  matched:
                    items:
                      type: string
                    type: array
                  reason:
                    type: string
                required:
                  - allow
                  - matched
                  - reason
                type: object
              example:
                allow: true
                matched:
                  - orders:read:team
                reason: permission granted
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: subject is required
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a service subject is required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested user was not found
        "422":
          description: Invalid Permission
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Permission
                status: 422
                detail: permission must use resource:action:scope grammar
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authorization service unavailable
      security:
        - bearerAuth: []
  /authz/permissions/{userID}:
    get:
      tags:
        - Authorization
      summary: List effective grants
      description: Use from a trusted service to refresh a permission cache for one user. Send GET /authz/permissions/{userID}?version=2; the service-kind bearer token is required. Missing or non-2 versions return 400 rather than an unsafe flattened snapshot. The v2 response carries version, user_id, perm_ver, grants with optional condition and team_id, and optional RFC 3339 valid_until (the earliest future membership or binding expiry affecting grants). Platform grants omit team_id; scoped grants include a non-empty team_id. Clients must require response version=2 and all required v2 fields, strictly validate defined field and grant types/shapes, and ignore unknown additive fields at the snapshot or grant level. Unknown fields add no security semantics; future security-semantic changes require an explicit version. SDKs clamp cache expiry to valid_until.
      parameters:
        - name: userID
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  grants:
                    items:
                      properties:
                        condition:
                          anyOf:
                            - type: string
                            - type: "null"
                        key:
                          type: string
                        team_id:
                          anyOf:
                            - type: string
                            - type: "null"
                      required:
                        - key
                      type: object
                    type: array
                  perm_ver:
                    type: integer
                  user_id:
                    type: string
                  valid_until:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  version:
                    type: integer
                required:
                  - version
                  - user_id
                  - perm_ver
                  - grants
                type: object
              example:
                grants:
                  - key: reports:read:any
                  - condition: resource.attrs["region"] == "us-east-1"
                    key: orders:read:team
                    team_id: 01J8Z3TEAM000000000000001
                perm_ver: 3
                user_id: 01J8Z3USER000000000000001
                valid_until: "2026-11-01T00:00:00Z"
                version: 2
        "400":
          description: Unsupported Permission Snapshot Version
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unsupported Permission Snapshot Version
                status: 400
                detail: version=2 is required; legacy snapshots are not supported
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested user was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authorization service unavailable
      security:
        - bearerAuth: []
  /bindings/:
    get:
      tags:
        - Bindings
      summary: List role bindings for a subject
      description: Lists a user's or group's role assignments or a team's singleton baseline for the required `subject_kind` and `subject_id`, ordered by ascending binding ID. `iam:bindings:team` authorizes group/team queries for an active target team; user-wide queries require platform `iam:bindings:any`. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        condition:
                          anyOf:
                            - type: string
                            - type: "null"
                        expires_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        id:
                          type: string
                        role_id:
                          type: string
                        subject_id:
                          type: string
                        subject_kind:
                          type: string
                        team_id:
                          anyOf:
                            - type: string
                            - type: "null"
                      required:
                        - id
                        - role_id
                        - subject_kind
                        - subject_id
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - condition: resource.team_id == "01J8Z3TEAM000000000000001"
                    id: 01J8Z3BIND000000000000001
                    role_id: 01J8Z3ROLE000000000000001
                    subject_id: 01J8Z3TEAM000000000000001
                    subject_kind: team
                    team_id: 01J8Z3TEAM000000000000001
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: subject_kind and subject_id are required
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:bindings:any
        team: iam:bindings:team
    post:
      tags:
        - Bindings
      summary: Create a role binding
      description: Use to assign a role to a user or group, or create one team's singleton baseline with subject_kind=team and subject_id equal to the team ID. For a baseline, team_id may be omitted/inferred or must equal subject_id; the role may be platform-scoped or belong to that team, but never a foreign team. Conditions and deny permissions are allowed, and expires_at is forbidden. Every user with at least one unexpired membership in a group within the active team inherits the role; the baseline stops applying after the user's last such membership expires or is removed. A duplicate baseline returns 409. User/group bindings retain expiry semantics. A successful create returns 201. Team-bound grants stay confined to their active resource team, including keys ending in :any. A matching team-baseline deny defeats a matching platform allow for an eligible member's resource in that team; an outsider, including a platform administrator without active membership, does not inherit the baseline deny and retains independent platform grants.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                condition:
                  anyOf:
                    - type: string
                    - type: "null"
                expires_at:
                  anyOf:
                    - format: date-time
                      type: string
                    - type: "null"
                role_id:
                  type: string
                subject_id:
                  type: string
                subject_kind:
                  type: string
                team_id: true
              required:
                - role_id
                - subject_kind
                - subject_id
              type: object
            example:
              condition: resource.team_id == "01J8Z3TEAM000000000000001"
              role_id: 01J8Z3ROLE000000000000001
              subject_id: 01J8Z3TEAM000000000000001
              subject_kind: team
              team_id: 01J8Z3TEAM000000000000001
      responses:
        "201":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  condition:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  id:
                    type: string
                  role_id:
                    type: string
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - id
                  - role_id
                  - subject_kind
                  - subject_id
                type: object
              example:
                condition: resource.team_id == "01J8Z3TEAM000000000000001"
                id: 01J8Z3BIND000000000000001
                role_id: 01J8Z3ROLE000000000000001
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request; Invalid Request; Invalid Request; Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                request body must be valid JSON:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: request body must be valid JSON
                team baseline requires matching team_id and subject_id:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: team baseline requires matching team_id and subject_id
                team baseline bindings cannot expire:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: team baseline bindings cannot expire
                team baseline role must belong to the same team:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: team baseline role must belong to the same team
                binding team_id does not match role team_id:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: binding team_id does not match role team_id
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "409":
          description: Conflict; Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                the resource already exists:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: the resource already exists
                a team baseline binding already exists:
                  value:
                    type: about:blank
                    title: Conflict
                    status: 409
                    detail: a team baseline binding already exists
        "422":
          description: Invalid Condition
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Condition
                status: 422
                detail: condition could not be compiled
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:bindings:any
        team: iam:bindings:team
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /bindings/{id}:
    delete:
      tags:
        - Bindings
      summary: Delete a role binding
      description: Use to remove a user or group role assignment or a team's singleton baseline. iam:bindings:team can remove bindings only for its active target team; independent platform iam:bindings:any can maintain disabled teams. The deletion is audited and affected users' permission versions are invalidated, including every member inheriting the baseline.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:bindings:any
        team: iam:bindings:team
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
    get:
      tags:
        - Bindings
      summary: Get a role binding
      description: 'Use to retrieve one binding by ID, including its persisted team scope and subject. A binding with `team_id: null` is platform-scoped; team-targeted bindings are authorized against their existing team.'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  condition:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  id:
                    type: string
                  role_id:
                    type: string
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - id
                  - role_id
                  - subject_kind
                  - subject_id
                type: object
              example:
                condition: resource.team_id == "01J8Z3TEAM000000000000001"
                id: 01J8Z3BIND000000000000001
                role_id: 01J8Z3ROLE000000000000001
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                team_id: 01J8Z3TEAM000000000000001
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:bindings:any
        team: iam:bindings:team
        note: 'Requires `iam:bindings:any`, or an applicable `iam:bindings:team` grant for the binding''s active target team; platform bindings (`team_id: null`) require `iam:bindings:any`. Reads do not require step-up authentication.'
    patch:
      tags:
        - Bindings
      summary: Update a role binding
      description: Use to replace role_id and/or condition on an existing binding. Omitted values remain unchanged; send condition:null to clear the condition. subject_kind, subject_id, team_id, and expires_at are immutable; team baselines remain permanent and accept only a platform-scoped or same-team role. iam:bindings:team can update bindings only for its active target team; independent platform iam:bindings:any can maintain disabled teams. A team-scoped binding can only target its active team and cannot turn a :any key into platform access.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                condition: true
                expires_at: true
                role_id: true
                subject_id: true
                subject_kind: true
                team_id: true
              required:
                - role_id
                - condition
                - team_id
                - subject_kind
                - subject_id
                - expires_at
              type: object
            example:
              condition: resource.attrs["region"] == "us-east-1"
              role_id: 01J8Z3ROLE000000000000002
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  condition:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  id:
                    type: string
                  role_id:
                    type: string
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - id
                  - role_id
                  - subject_kind
                  - subject_id
                type: object
              example:
                condition: resource.attrs["region"] == "us-east-1"
                id: 01J8Z3BIND000000000000001
                role_id: 01J8Z3ROLE000000000000002
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request; Invalid Request; Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                request body must be valid JSON:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: request body must be valid JSON
                binding identity and scope cannot be changed:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: binding identity and scope cannot be changed
                team baseline role must belong to the same team:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: team baseline role must belong to the same team
                binding team_id does not match role team_id:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: binding team_id does not match role team_id
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Invalid Condition
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Condition
                status: 422
                detail: condition could not be compiled
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:bindings:any
        team: iam:bindings:team
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /groups/:
    get:
      tags:
        - Groups
      summary: List groups in a team
      description: Lists groups for one required `team_id`, ordered by ascending group ID. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        team_id:
                          type: string
                      required:
                        - id
                        - team_id
                        - name
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - id: 01J8Z3GROUP000000000000001
                    name: backend
                    team_id: 01J8Z3TEAM000000000000001
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
    post:
      tags:
        - Groups
      summary: Create a group
      description: Use to create a team-scoped group that can receive memberships and role bindings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                team_id:
                  type: string
              required:
                - team_id
                - name
              type: object
            example:
              name: backend
              team_id: 01J8Z3TEAM000000000000001
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  team_id:
                    type: string
                required:
                  - id
                  - team_id
                  - name
                type: object
              example:
                id: 01J8Z3GROUP000000000000001
                name: backend
                team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: the resource already exists
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
  /groups/{id}:
    delete:
      tags:
        - Groups
      summary: Delete a group
      description: Use to remove a group and its memberships. Affected users' permission versions are invalidated.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
    get:
      tags:
        - Groups
      summary: Get a group
      description: Use to retrieve one group by ULID, including its owning team ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  team_id:
                    type: string
                required:
                  - id
                  - team_id
                  - name
                type: object
              example:
                id: 01J8Z3GROUP000000000000001
                name: backend
                team_id: 01J8Z3TEAM000000000000001
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
    patch:
      tags:
        - Groups
      summary: Update a group
      description: Use to rename a group or move it to another team. At least one of team_id and name is required; memberships are updated when the team changes.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  anyOf:
                    - type: string
                    - type: "null"
                team_id:
                  anyOf:
                    - type: string
                    - type: "null"
              type: object
            example:
              name: platform-backend
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  team_id:
                    type: string
                required:
                  - id
                  - team_id
                  - name
                type: object
              example:
                id: 01J8Z3GROUP000000000000001
                name: platform-backend
                team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
  /groups/{id}/members:
    delete:
      tags:
        - Groups
      summary: Remove a group member by request body
      description: Use to remove a membership when the client has the group ID but sends the user ID as JSON. The path variant with userID is equivalent and is preferred for idempotent URL-based clients.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                expires_at:
                  anyOf:
                    - format: date-time
                      type: string
                    - type: "null"
                user_id:
                  type: string
              required:
                - user_id
              type: object
            example:
              user_id: 01J8Z3USER000000000000001
      responses:
        "204":
          description: No Content
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
    get:
      tags:
        - Groups
      summary: List group members
      description: Lists membership records for the path group in ascending `user_id` order. The cursor key is the user ID. See [REST collection pagination](/guide/pagination) for the shared collection contract.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        expires_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        group_id:
                          type: string
                        team_id:
                          type: string
                        user_id:
                          type: string
                      required:
                        - team_id
                        - group_id
                        - user_id
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - expires_at: "2026-02-01T00:00:00Z"
                    group_id: 01J8Z3GROUP000000000000001
                    team_id: 01J8Z3TEAM000000000000001
                    user_id: 01J8Z3USER000000000000001
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
        note: Requires `iam:groups:any` or an applicable `iam:groups:team` grant for the group's active owning team; reads do not require step-up authentication.
    put:
      tags:
        - Groups
      summary: Add or replace a group membership
      description: Use to add a user to a group or update that membership's expiry. The operation is idempotent and returns the complete membership record.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                expires_at:
                  anyOf:
                    - format: date-time
                      type: string
                    - type: "null"
                user_id:
                  type: string
              required:
                - user_id
              type: object
            example:
              expires_at: "2026-02-01T00:00:00Z"
              user_id: 01J8Z3USER000000000000001
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  expires_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  group_id:
                    type: string
                  team_id:
                    type: string
                  user_id:
                    type: string
                required:
                  - team_id
                  - group_id
                  - user_id
                type: object
              example:
                expires_at: "2026-02-01T00:00:00Z"
                group_id: 01J8Z3GROUP000000000000001
                team_id: 01J8Z3TEAM000000000000001
                user_id: 01J8Z3USER000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /groups/{id}/members/batch:
    post:
      tags:
        - Groups
      summary: Add group members in a batch
      description: Use to bulk-populate a group. Up to 500 user IDs are processed independently; duplicate rows report already_member and unknown users report not_found.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                user_ids:
                  items:
                    type: string
                  type: array
              type: object
            example:
              user_ids:
                - 01J8Z3USER000000000000001
                - 01J8Z3USER000000000000002
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                results:
                  - id: 01J8Z3USER000000000000001
                    ok: true
                  - error: already_member
                    id: 01J8Z3USER000000000000002
                    ok: false
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Too Many Items
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Items
                status: 422
                detail: a maximum of 500 user_ids is allowed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /groups/{id}/members/{userID}:
    delete:
      tags:
        - Groups
      summary: Remove a group member
      description: Use to remove a membership by group and user ULIDs. Unknown group, user, or membership returns a generic not-found problem.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: userID
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
    get:
      tags:
        - Groups
      summary: Get a group membership
      description: Use to retrieve one membership by group and user IDs, including its expiry when present. An unknown group, user, or membership returns the same generic not-found response.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: userID
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  expires_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  group_id:
                    type: string
                  team_id:
                    type: string
                  user_id:
                    type: string
                required:
                  - team_id
                  - group_id
                  - user_id
                type: object
              example:
                expires_at: "2026-02-01T00:00:00Z"
                group_id: 01J8Z3GROUP000000000000001
                team_id: 01J8Z3TEAM000000000000001
                user_id: 01J8Z3USER000000000000001
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:groups:any
        team: iam:groups:team
        note: Requires `iam:groups:any` or an applicable `iam:groups:team` grant for the group's active owning team; reads do not require step-up authentication.
  /healthz:
    get:
      tags:
        - Health
      summary: Check liveness
      description: Use this inexpensive unauthenticated probe to determine whether the HTTP process is alive. Load balancers and orchestrators call it without credentials.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
              example:
                status: ok
      security: []
  /impersonations:
    post:
      tags:
        - Impersonation
      summary: Start an audited user impersonation
      description: Use for time-bounded administrative support as an active user. Requires iam:impersonate:any and a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. The target must be active, must not be a service account or the caller, and must not hold effective IAM permissions. The required reason is recorded with the actor, target, TTL, token jti, and exact expires_at in the append-only audit log. The returned user-kind access token has no refresh token or session, carries act and imp claims, sets auth_time to zero, and cannot use MFA-only step-up or satisfy freshness guards.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                reason:
                  type: string
                ttl_seconds:
                  anyOf:
                    - type: integer
                    - type: "null"
                user_id:
                  type: string
              required:
                - user_id
                - reason
              type: object
            example:
              reason: investigate support request
              ttl_seconds: 300
              user_id: 01J8Z3USER000000000000001
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  access_token:
                    type: string
                  expires_at:
                    format: date-time
                    type: string
                  token_type:
                    type: string
                required:
                  - access_token
                  - token_type
                  - expires_at
                type: object
              example:
                access_token: signed-user-token
                expires_at: "2026-01-01T00:05:00Z"
                token_type: Bearer
        "400":
          description: Invalid Request; Invalid Request; Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                request body must be valid JSON:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: request body must be valid JSON
                user_id is required:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: user_id is required
                reason must be at least 3 characters:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: reason must be at least 3 characters
                ttl_seconds must be between 1 and 900:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: ttl_seconds must be between 1 and 900
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
                the target user must be active:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: the target user must be active
                self-impersonation is not allowed:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: self-impersonation is not allowed
                service accounts cannot be impersonated:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: service accounts cannot be impersonated
                the target user is not eligible for impersonation:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: the target user is not eligible for impersonation
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "409":
          description: Idempotency In Progress
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency In Progress
                status: 409
                detail: idempotency_in_progress
        "422":
          description: Idempotency Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency Conflict
                status: 422
                detail: idempotency_conflict
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:impersonate:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /invitations/:
    post:
      tags:
        - Invitations
      summary: Create an invitation
      description: Use from an administrator provisioning workflow to create an invited user and send a one-time invitation token. Username and email must be unique; the plaintext token is emitted only through notification delivery.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                display_name:
                  type: string
                email:
                  type: string
                username:
                  type: string
              required:
                - email
                - username
              type: object
            example:
              display_name: Alice Example
              email: alice@example.test
              username: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
              example:
                id: 01J8Z3USER000000000000001
                status: invited
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "422":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 422
                detail: username or email already exists
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
  /invitations/{userID}:
    delete:
      tags:
        - Invitations
      summary: Cancel an invitation
      description: Use when an invitation must be withdrawn before acceptance. The target must remain invited; cancellation deletes the user and cascaded records.
      parameters:
        - name: userID
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 422
                detail: account is not invited
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
  /invitations/{userID}/resend:
    post:
      tags:
        - Invitations
      summary: Resend an invitation
      description: Use when an invited user did not receive the original message. The previous invitation token is invalidated and a fresh seven-day token is emitted through notifications.
      parameters:
        - name: userID
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 422
                detail: account is not invited
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
  /keys/rotate:
    post:
      tags:
        - Keys
      summary: Rotate the active signing key
      description: Use during a signing-key maintenance window. The new EdDSA key signs immediately; the previous public key remains in JWKS for twice the configured access-token TTL. Accepts Idempotency-Key for safe retries.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  kid:
                    type: string
                  retire_at:
                    format: date-time
                    type: string
                  warning:
                    type: string
                required:
                  - kid
                  - retire_at
                type: object
              example:
                kid: 01J8Z3KEY00000000000000002
                retire_at: "2026-01-01T00:20:00Z"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "409":
          description: Idempotency In Progress
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency In Progress
                status: 409
                detail: idempotency_in_progress
        "422":
          description: Idempotency Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Idempotency Conflict
                status: 422
                detail: idempotency_conflict
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:keys:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /me:
    delete:
      tags:
        - Self-service
      summary: Erase the current account
      description: Use when a user requests irreversible account erasure. The password is rechecked; profile identifiers are anonymized, all credentials and sessions are removed, and the account is disabled.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                password:
                  type: string
              required:
                - password
              type: object
            example:
              password: CurrentAtLeastTwelve1
      responses:
        "204":
          description: No Content
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: invalid_credentials
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_credentials
                status: 401
                detail: invalid_credentials
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
    get:
      tags:
        - Self-service
      summary: Get the current profile
      description: Use from a signed-in user interface to display the authenticated user's profile. The identity is always taken from the user bearer subject; credentials and other users' data are never returned.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  id:
                    type: string
                  status:
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Example
                email: alice@example.test
                email_verified_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3USER000000000000001
                status: active
                username: alice
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
    patch:
      tags:
        - Self-service
      summary: Update the current profile
      description: Use when a user edits their own username or display name. Username is trimmed using the same rules as administrative user updates; email changes use the two-step email endpoints. At least one of username or display_name is required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                display_name:
                  type: string
                username:
                  type: string
              type: object
            example:
              display_name: Alice Smith
              username: alice-new
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  id:
                    type: string
                  status:
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Smith
                email: alice@example.test
                email_verified_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3USER000000000000001
                status: active
                username: alice-new
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: at least one of username or display_name is required
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: the resource already exists
        "422":
          description: Invalid Request; Invalid Request; Unsupported Field; Unsupported Field
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                username is required:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 422
                    detail: username is required
                username must be a string:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 422
                    detail: username must be a string
                unsupported_field:
                  value:
                    type: about:blank
                    title: Unsupported Field
                    status: 422
                    detail: unsupported_field
                email change is not supported:
                  value:
                    type: about:blank
                    title: Unsupported Field
                    status: 422
                    detail: email change is not supported
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/activity:
    get:
      tags:
        - Sessions
      summary: List the current user's login activity
      description: Use in account security settings to review this user's resolved password, passkey, MFA, and OIDC login attempts. The method values are `password`, `passkey`, `mfa`, and `oidc` respectively; `step_up` records MFA-only step-up verification (see POST /auth/step-up/begin and POST /auth/step-up/complete). Results contain only rows whose `user_id` matches the bearer subject and are ordered by descending numeric activity ID. The `cursor` is a non-negative decimal string ID (omit, leave empty, or use `0` for the newest page); IDs remain numeric in `items`. See [REST pagination](/guide/pagination) for the shared limit, envelope, and terminal-cursor contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        at:
                          format: date-time
                          type: string
                        id:
                          type: integer
                        ip:
                          type: string
                        method:
                          type: string
                        result:
                          type: string
                        user_agent:
                          type: string
                        user_id:
                          type: string
                      required:
                        - id
                        - user_id
                        - at
                        - ip
                        - user_agent
                        - method
                        - result
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - at: "2026-01-02T12:00:00Z"
                    id: !!float 42
                    ip: 203.0.113.5
                    method: password
                    result: success
                    user_agent: ExampleBrowser/1.0
                    user_id: 01J8Z3USER000000000000001
                next_cursor: ""
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                cursor must be a non-negative integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: cursor must be a non-negative integer
                limit must be a positive integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/email:
    post:
      tags:
        - Self-service
      summary: Request an email change
      description: Use when a user wants to replace their email. The current password is required; a single-use verification token is sent to the new address and the profile remains unchanged until confirmation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                new_email:
                  type: string
                password:
                  type: string
              required:
                - new_email
                - password
              type: object
            example:
              new_email: alice.new@example.test
              password: CurrentAtLeastTwelve1
      responses:
        "204":
          description: No Content
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: invalid_credentials
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_credentials
                status: 401
                detail: invalid_credentials
        "422":
          description: invalid_email; email_taken
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                invalid_email:
                  value:
                    type: about:blank
                    title: invalid_email
                    status: 422
                    detail: invalid_email
                email_taken:
                  value:
                    type: about:blank
                    title: email_taken
                    status: 422
                    detail: email_taken
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/email/confirm:
    post:
      tags:
        - Self-service
      summary: Confirm an email change
      description: Use with the one-time token sent to the replacement address. The token is bound to the bearer subject; success updates email_verified_at and the email atomically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                token:
                  type: string
              required:
                - token
              type: object
            example:
              token: email-change-token-from-email
      responses:
        "204":
          description: No Content
        "400":
          description: invalid_token
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_token
                status: 400
                detail: invalid_token
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/export:
    get:
      tags:
        - Self-service
      summary: Export current account data
      description: Use to satisfy a data portability request. The response is an attachment containing profile, memberships, effective permissions, active sessions, and MFA/passkey counts; secrets and credential material are excluded.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  active_sessions:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        expires_at:
                          format: date-time
                          type: string
                        id:
                          type: string
                        last_active_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - created_at
                        - last_active_at
                        - expires_at
                      type: object
                    type: array
                  effective_permissions:
                    items:
                      type: string
                    type: array
                  memberships:
                    items:
                      properties:
                        group_id:
                          type: string
                        team_id:
                          type: string
                      required:
                        - group_id
                        - team_id
                      type: object
                    type: array
                  passkey_count:
                    type: integer
                  profile:
                    properties:
                      created_at:
                        format: date-time
                        type: string
                      display_name:
                        type: string
                      email:
                        anyOf:
                          - type: string
                          - type: "null"
                      email_verified_at:
                        anyOf:
                          - format: date-time
                            type: string
                          - type: "null"
                      id:
                        type: string
                      status:
                        type: string
                      username:
                        type: string
                    required:
                      - id
                      - username
                      - display_name
                      - status
                      - created_at
                    type: object
                  totp_enabled:
                    type: boolean
                required:
                  - profile
                  - memberships
                  - effective_permissions
                  - active_sessions
                  - totp_enabled
                  - passkey_count
                type: object
              example:
                active_sessions:
                  - created_at: "2026-01-01T00:00:00Z"
                    expires_at: "2026-01-31T00:00:00Z"
                    id: 8d7e5b3a0f6f4e1d...
                effective_permissions:
                  - orders:read:team
                memberships:
                  - group_id: 01J8Z3GROUP000000000000001
                    team_id: 01J8Z3TEAM000000000000001
                passkey_count: 0
                profile:
                  created_at: "2026-01-01T00:00:00Z"
                  display_name: Alice Example
                  email: alice@example.test
                  email_verified_at: "2026-01-01T00:00:00Z"
                  id: 01J8Z3USER000000000000001
                  status: active
                  username: alice
                totp_enabled: false
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/passkeys:
    get:
      tags:
        - Self-service
      summary: List own passkeys
      description: Lists the current user's registered passkey identifiers in lexicographic order by canonical unpadded base64url credential ID. The exposed `id` is also the cursor key; malformed or noncanonical cursors return HTTP 400. Public keys and attestation data are never returned. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        id:
                          type: string
                      required:
                        - id
                        - created_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    id: Y3JlZGVudGlhbC1pZA
                next_cursor: ""
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                limit must be a positive integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: limit must be a positive integer
                cursor must be a canonical unpadded base64url credential ID:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: cursor must be a canonical unpadded base64url credential ID
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/passkeys/register/begin:
    post:
      tags:
        - Self-service
      summary: Begin passkey registration
      description: Use from a signed-in browser to add a WebAuthn credential. The browser passes the returned publicKey options to navigator.credentials.create; the ceremony expires after five minutes.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                publicKey:
                  attestation: none
                  challenge: base64url-challenge
                  pubKeyCredParams:
                    - alg: -7
                      type: public-key
                  rp:
                    id: localhost
                    name: teamusers
                  user:
                    displayName: Alice Example
                    id: base64url-user-handle
                    name: alice
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/passkeys/register/finish:
    post:
      tags:
        - Self-service
      summary: Finish passkey registration
      description: Use with the browser's PublicKeyCredential creation response. A valid response consumes the single-use challenge and stores only the credential material required for WebAuthn.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                id:
                  type: string
                rawId:
                  type: string
                response:
                  additionalProperties:
                    type: string
                  type: object
                type:
                  type: string
              required:
                - id
                - rawId
                - type
                - response
              type: object
            example:
              id: base64url-credential-id
              rawId: base64url-credential-id
              response:
                attestationObject: base64url-attestation
                clientDataJSON: base64url-client-data
              type: public-key
      responses:
        "204":
          description: No Content
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: invalid WebAuthn response
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/passkeys/{credID}:
    delete:
      tags:
        - Self-service
      summary: Delete one own passkey
      description: Use to remove a passkey by its unpadded base64url credential ID. Unknown IDs return the same not-found problem regardless of ownership.
      parameters:
        - name: credID
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested passkey was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/password:
    post:
      tags:
        - Self-service
      summary: Change the current password
      description: Use when a signed-in user rotates their password. The current password is verified, the replacement must satisfy policy, and every refresh session (including the current one) is revoked. A first-login change_token from POST /auth/login is accepted as the bearer in place of an access token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                current_password:
                  type: string
                new_password:
                  type: string
              required:
                - current_password
                - new_password
              type: object
            example:
              current_password: OldAtLeastTwelve1
              new_password: NewAtLeastTwelve2
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                message: password changed; all sessions were revoked; sign in again
                sessions_revoked: true
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: invalid_credentials
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_credentials
                status: 401
                detail: invalid_credentials
        "422":
          description: weak_password
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: weak_password
                status: 422
                detail: weak_password
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/password-policy:
    get:
      tags:
        - Self-service
      summary: Get the effective password policy
      description: Use to display the password requirements currently resolved for the authenticated user. Only the merged policy is returned; the endpoint requires a user bearer.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  breach_check:
                    type: boolean
                  history_count:
                    type: integer
                  min_length:
                    type: integer
                  require_digit:
                    type: boolean
                  require_letter:
                    type: boolean
                  require_lower:
                    type: boolean
                  require_symbol:
                    type: boolean
                  require_upper:
                    type: boolean
                required:
                  - min_length
                  - require_letter
                  - require_upper
                  - require_lower
                  - require_digit
                  - require_symbol
                  - history_count
                  - breach_check
                type: object
              example:
                breach_check: true
                history_count: 5
                min_length: 12
                require_digit: true
                require_letter: true
                require_lower: false
                require_symbol: false
                require_upper: false
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/permissions:
    get:
      tags:
        - Self-service
      summary: List permission keys for display
      description: Returns the authenticated user's flat list of unconditional permission keys from direct, group, and team-baseline role bindings; a baseline is included while the user has any unexpired group membership in that active team. The existing flat `permissions` string-array response contains neither per-grant `team_id` nor target-resource context, so treat it only as an informational/UI list, not authorization evidence or a final allow/deny result for any resource. It cannot resolve deny-overrides across every applicable platform and matching target-team grant for a specific resource. Bindings with non-empty ABAC conditions are omitted because no request-specific resource context is available; disabled users resolve to an empty permission list. For an authorization decision, use contextual `POST /authz/check` with the actual resource or evaluate v2 grants from `GET /authz/permissions/{userID}?version=2` against the resource, including `team_id`.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  permissions:
                    items:
                      type: string
                    type: array
                required:
                  - permissions
                type: object
              example:
                permissions:
                  - docs:read:team
                  - orders:read:own
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: impersonation_forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: impersonation_forbidden
                status: 403
                detail: impersonation_forbidden
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/sessions:
    get:
      tags:
        - Sessions
      summary: List the current user's sessions
      description: Lists active, unexpired refresh sessions belonging to the bearer user, ordered by `created_at` ascending and session ID ascending. Returned IDs are opaque token digests and each row contains `created_at`, `last_active_at`, and `expires_at`. The cursor is an opaque composite of the full ordering key. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        expires_at:
                          format: date-time
                          type: string
                        id:
                          type: string
                        last_active_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - created_at
                        - last_active_at
                        - expires_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    expires_at: "2026-01-31T00:00:00Z"
                    id: 8d7e5b3a0f6f4e1d...
                    last_active_at: "2026-01-02T12:00:00Z"
                next_cursor: ""
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                limit must be a positive integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: limit must be a positive integer
                cursor is not a valid session cursor:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: cursor is not a valid session cursor
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/sessions/{id}:
    delete:
      tags:
        - Sessions
      summary: Revoke one own session
      description: Use when a user signs out another browser or device. Foreign, expired, revoked, or unknown IDs all return the same 404 response.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/totp:
    delete:
      tags:
        - Self-service
      summary: Disable TOTP
      description: Use when a user removes MFA. Submit a current TOTP code or unused backup code; active TOTP, pending TOTP, and backup credentials are deleted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                code:
                  type: string
              required:
                - code
              type: object
            example:
              code: "123456"
      responses:
        "204":
          description: No Content
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/totp/backup-codes:
    post:
      tags:
        - Self-service
      summary: Regenerate TOTP backup codes
      description: Use when backup codes are exhausted or suspected exposed. The current password and an active TOTP enrollment are required; old codes are replaced atomically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                password:
                  type: string
              required:
                - password
              type: object
            example:
              password: CurrentAtLeastTwelve1
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  backup_codes:
                    items:
                      type: string
                    type: array
                required:
                  - backup_codes
                type: object
              example:
                backup_codes:
                  - abcd-1234-efgh-5678
                  - 9ijk-lmno-0123-pqrs
                  - 1111-2222-3333-4444
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: invalid_credentials
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: invalid_credentials
                status: 401
                detail: invalid_credentials
        "404":
          description: mfa_not_enrolled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: mfa_not_enrolled
                status: 404
                detail: mfa_not_enrolled
        "429":
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Too Many Requests
                status: 429
                detail: authentication temporarily busy
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/totp/confirm:
    post:
      tags:
        - Self-service
      summary: Confirm TOTP enrollment
      description: Use after scanning the enrollment QR code. Submit the current six-digit code; the pending secret becomes active and ten one-time backup codes are returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                code:
                  type: string
              required:
                - code
              type: object
            example:
              code: "123456"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  backup_codes:
                    items:
                      type: string
                    type: array
                required:
                  - backup_codes
                type: object
              example:
                backup_codes:
                  - abcd-1234-efgh-5678
                  - 9ijk-lmno-0123-pqrs
                  - 1111-2222-3333-4444
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "409":
          description: totp_already_enabled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: totp_already_enabled
                status: 409
                detail: totp_already_enabled
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /me/totp/enroll:
    post:
      tags:
        - Self-service
      summary: Start TOTP enrollment
      description: Use in security settings to start MFA enrollment. The returned secret and otpauth URL are displayed once; the credential remains pending until a code is confirmed.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  otpauth_url:
                    type: string
                  secret:
                    type: string
                required:
                  - secret
                  - otpauth_url
                type: object
              example:
                otpauth_url: otpauth://totp/teamusers:alice?secret=JBSWY3DPEHPK3PXP&issuer=teamusers
                secret: JBSWY3DPEHPK3PXP
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "409":
          description: totp_already_enabled
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: totp_already_enabled
                status: 409
                detail: totp_already_enabled
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
  /permissions/:
    get:
      tags:
        - Permissions
      summary: List registered permissions
      description: Use to populate policy editors and validate role changes; lists registered permission keys in ascending order. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        description:
                          type: string
                        key:
                          type: string
                        registered_by:
                          type: string
                      required:
                        - key
                        - description
                        - registered_by
                        - created_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    description: Read orders in a team
                    key: orders:read:team
                    registered_by: orders-service
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:permissions:any
    post:
      tags:
        - Permissions
      summary: Register or update a permission
      description: Use when an application service introduces a permission key. Keys must follow resource:action:scope grammar, with an optional ! deny prefix; registration is an upsert and increments the global permission registry version.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                key:
                  type: string
                registered_by:
                  type: string
              required:
                - key
                - registered_by
              type: object
            example:
              description: Read orders in a team
              key: orders:read:team
              registered_by: orders-service
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  description:
                    type: string
                  key:
                    type: string
                  registered_by:
                    type: string
                required:
                  - key
                  - description
                  - registered_by
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                description: Read orders in a team
                key: orders:read:team
                registered_by: orders-service
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "422":
          description: Invalid Permission
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Permission
                status: 422
                detail: permission must use resource:action:scope grammar
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:permissions:any
  /permissions/{key}:
    get:
      tags:
        - Permissions
      summary: Get a registered permission
      description: Use to retrieve one registered permission by exact key. The key occupies one path segment; an optional `!` deny prefix is part of the key. Unknown or syntactically invalid keys return the standard not-found response.
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  description:
                    type: string
                  key:
                    type: string
                  registered_by:
                    type: string
                required:
                  - key
                  - description
                  - registered_by
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                description: Read orders in a team
                key: orders:read:team
                registered_by: orders-service
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:permissions:any
        note: Requires `iam:permissions:any`; reads do not require step-up authentication.
  /policies/mfa:
    get:
      tags:
        - Policies
      summary: List MFA policies
      description: Lists policies that require or allow MFA for users, teams, groups, roles, or all users, ordered by policy ID. Changes are audited and apply at the next login without revoking existing sessions. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        deny_unenrolled:
                          type: boolean
                        id:
                          type: string
                        name:
                          type: string
                        priority:
                          type: integer
                        required:
                          type: boolean
                        subject_id:
                          type: string
                        subject_kind:
                          type: string
                        updated_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - name
                        - priority
                        - subject_kind
                        - subject_id
                        - required
                        - deny_unenrolled
                        - created_at
                        - updated_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    id: 01J8Z3MFAPOLICY0000000000001
                    name: team MFA
                    priority: 100
                    required: true
                    subject_id: 01J8Z3TEAM000000000000001
                    subject_kind: team
                    updated_at: "2026-01-01T00:00:00Z"
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
    post:
      tags:
        - Policies
      summary: Create an MFA policy
      description: Use to create an MFA requirement for an existing team, group, role, or the default population. The highest-priority matching policy applies at password or passkey login; policy mutations are audited.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                deny_unenrolled:
                  type: boolean
                name:
                  type: string
                priority:
                  type: integer
                required:
                  anyOf:
                    - type: boolean
                    - type: "null"
                subject_id:
                  type: string
                subject_kind:
                  type: string
              required:
                - subject_kind
                - required
              type: object
            example:
              name: team MFA
              priority: 100
              required: true
              subject_id: 01J8Z3TEAM000000000000001
              subject_kind: team
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  deny_unenrolled:
                    type: boolean
                  id:
                    type: string
                  name:
                    type: string
                  priority:
                    type: integer
                  required:
                    type: boolean
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - name
                  - priority
                  - subject_kind
                  - subject_id
                  - required
                  - deny_unenrolled
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3MFAPOLICY0000000000001
                name: team MFA
                priority: 100
                required: true
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                updated_at: "2026-01-01T00:00:00Z"
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "422":
          description: Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                subject_kind must be one of default, team, group, role:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_kind must be one of default, team, group, role
                subject_id is required:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_id is required
                subject does not exist:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject does not exist
                priority must be between -2147483648 and 2147483647:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: priority must be between -2147483648 and 2147483647
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /policies/mfa/{id}:
    delete:
      tags:
        - Policies
      summary: Delete an MFA policy
      description: Use to remove an MFA policy. The deletion is audited and returns no body.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
    get:
      tags:
        - Policies
      summary: Get an MFA policy
      description: Use to retrieve one MFA policy before editing or removing it.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  deny_unenrolled:
                    type: boolean
                  id:
                    type: string
                  name:
                    type: string
                  priority:
                    type: integer
                  required:
                    type: boolean
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - name
                  - priority
                  - subject_kind
                  - subject_id
                  - required
                  - deny_unenrolled
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3MFAPOLICY0000000000001
                name: team MFA
                priority: 100
                required: true
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                updated_at: "2026-01-01T00:00:00Z"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
    patch:
      tags:
        - Policies
      summary: Update an MFA policy
      description: Use to partially update an MFA policy. Omitted fields remain unchanged; subject changes must refer to an existing team, group, or role.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                deny_unenrolled:
                  anyOf:
                    - type: boolean
                    - type: "null"
                name:
                  anyOf:
                    - type: string
                    - type: "null"
                priority:
                  anyOf:
                    - type: integer
                    - type: "null"
                required:
                  anyOf:
                    - type: boolean
                    - type: "null"
                subject_id:
                  anyOf:
                    - type: string
                    - type: "null"
                subject_kind:
                  anyOf:
                    - type: string
                    - type: "null"
              type: object
            example:
              priority: 200
              required: false
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  deny_unenrolled:
                    type: boolean
                  id:
                    type: string
                  name:
                    type: string
                  priority:
                    type: integer
                  required:
                    type: boolean
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - name
                  - priority
                  - subject_kind
                  - subject_id
                  - required
                  - deny_unenrolled
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3MFAPOLICY0000000000001
                name: team MFA
                priority: 200
                required: false
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                updated_at: "2026-01-01T00:00:00Z"
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                request body must be valid JSON:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: request body must be valid JSON
                at least one MFA policy field is required:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: at least one MFA policy field is required
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                subject_kind must be one of default, team, group, role:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_kind must be one of default, team, group, role
                subject_id is required:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_id is required
                subject does not exist:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject does not exist
                priority must be between -2147483648 and 2147483647:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: priority must be between -2147483648 and 2147483647
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /policies/password:
    get:
      tags:
        - Policies
      summary: List password policies
      description: Lists password policies targeting users, teams, groups, or roles, ordered by policy ID. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        breach_check:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        created_at:
                          format: date-time
                          type: string
                        history_count:
                          anyOf:
                            - type: integer
                            - type: "null"
                        id:
                          type: string
                        min_length:
                          anyOf:
                            - type: integer
                            - type: "null"
                        name:
                          type: string
                        priority:
                          type: integer
                        require_digit:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        require_letter:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        require_lower:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        require_symbol:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        require_upper:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        subject_id:
                          type: string
                        subject_kind:
                          type: string
                        updated_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - name
                        - priority
                        - subject_kind
                        - subject_id
                        - created_at
                        - updated_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - breach_check: true
                    history_count: 5
                    id: 01J8Z3POLICY00000000000001
                    min_length: 12
                    name: team baseline
                    priority: 100
                    subject_id: 01J8Z3TEAM000000000000001
                    subject_kind: team
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
    post:
      tags:
        - Policies
      summary: Create a password policy
      description: Use to create a password policy for an existing user, team, group, or role. When policies overlap, higher priority wins independently for each field; an unset field falls through to lower-priority policies and then to the built-in default.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                breach_check:
                  anyOf:
                    - type: boolean
                    - type: "null"
                history_count:
                  anyOf:
                    - type: integer
                    - type: "null"
                min_length:
                  anyOf:
                    - type: integer
                    - type: "null"
                name:
                  type: string
                priority:
                  type: integer
                require_digit:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_letter:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_lower:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_symbol:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_upper:
                  anyOf:
                    - type: boolean
                    - type: "null"
                subject_id:
                  type: string
                subject_kind:
                  type: string
              required:
                - subject_kind
                - subject_id
              type: object
            example:
              breach_check: true
              history_count: 5
              min_length: 12
              name: team baseline
              priority: 100
              require_digit: true
              require_letter: true
              subject_id: 01J8Z3TEAM000000000000001
              subject_kind: team
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  breach_check:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  history_count:
                    anyOf:
                      - type: integer
                      - type: "null"
                  id:
                    type: string
                  min_length:
                    anyOf:
                      - type: integer
                      - type: "null"
                  name:
                    type: string
                  priority:
                    type: integer
                  require_digit:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_letter:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_lower:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_symbol:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_upper:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - name
                  - priority
                  - subject_kind
                  - subject_id
                  - created_at
                  - updated_at
                type: object
              example:
                breach_check: true
                created_at: "2026-01-01T00:00:00Z"
                history_count: 5
                id: 01J8Z3POLICY00000000000001
                min_length: 12
                name: team baseline
                priority: 100
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                updated_at: "2026-01-01T00:00:00Z"
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "422":
          description: Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                subject_kind must be one of user, team, group, role:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_kind must be one of user, team, group, role
                subject_id is required:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_id is required
                subject does not exist:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject does not exist
                priority must be between -2147483648 and 2147483647:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: priority must be between -2147483648 and 2147483647
                min_length must be between 1 and 1024:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: min_length must be between 1 and 1024
                history_count must be between 0 and 24:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: history_count must be between 0 and 24
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /policies/password/{id}:
    delete:
      tags:
        - Policies
      summary: Delete a password policy
      description: Use to remove a password policy. The deletion is audited and returns no body.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
    get:
      tags:
        - Policies
      summary: Get a password policy
      description: Use to retrieve one password policy by ID before editing or removing it.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  breach_check:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  history_count:
                    anyOf:
                      - type: integer
                      - type: "null"
                  id:
                    type: string
                  min_length:
                    anyOf:
                      - type: integer
                      - type: "null"
                  name:
                    type: string
                  priority:
                    type: integer
                  require_digit:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_letter:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_lower:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_symbol:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_upper:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - name
                  - priority
                  - subject_kind
                  - subject_id
                  - created_at
                  - updated_at
                type: object
              example:
                breach_check: true
                created_at: "2026-01-01T00:00:00Z"
                history_count: 5
                id: 01J8Z3POLICY00000000000001
                min_length: 12
                name: team baseline
                priority: 100
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                updated_at: "2026-01-01T00:00:00Z"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
    patch:
      tags:
        - Policies
      summary: Update a password policy
      description: Use to partially update a password policy. Omitted fields remain unchanged; send null for nullable policy fields to clear them. When policies overlap, higher priority wins independently for each field; an unset field falls through to lower-priority policies and then to the built-in default.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                breach_check:
                  anyOf:
                    - type: boolean
                    - type: "null"
                history_count:
                  anyOf:
                    - type: integer
                    - type: "null"
                min_length:
                  anyOf:
                    - type: integer
                    - type: "null"
                name:
                  type: string
                priority:
                  type: integer
                require_digit:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_letter:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_lower:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_symbol:
                  anyOf:
                    - type: boolean
                    - type: "null"
                require_upper:
                  anyOf:
                    - type: boolean
                    - type: "null"
                subject_id:
                  type: string
                subject_kind:
                  type: string
              type: object
            example:
              breach_check: false
              history_count: 8
              min_length: 14
              name: strong team baseline
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  breach_check:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  history_count:
                    anyOf:
                      - type: integer
                      - type: "null"
                  id:
                    type: string
                  min_length:
                    anyOf:
                      - type: integer
                      - type: "null"
                  name:
                    type: string
                  priority:
                    type: integer
                  require_digit:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_letter:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_lower:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_symbol:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  require_upper:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  subject_id:
                    type: string
                  subject_kind:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                required:
                  - id
                  - name
                  - priority
                  - subject_kind
                  - subject_id
                  - created_at
                  - updated_at
                type: object
              example:
                breach_check: false
                created_at: "2026-01-01T00:00:00Z"
                history_count: 8
                id: 01J8Z3POLICY00000000000001
                min_length: 14
                name: strong team baseline
                priority: 100
                subject_id: 01J8Z3TEAM000000000000001
                subject_kind: team
                updated_at: "2026-01-01T00:00:00Z"
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity; Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                subject_kind must be one of user, team, group, role:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_kind must be one of user, team, group, role
                subject_id is required:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject_id is required
                subject does not exist:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: subject does not exist
                priority must be between -2147483648 and 2147483647:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: priority must be between -2147483648 and 2147483647
                min_length must be between 1 and 1024:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: min_length must be between 1 and 1024
                history_count must be between 0 and 24:
                  value:
                    type: about:blank
                    title: Unprocessable Entity
                    status: 422
                    detail: history_count must be between 0 and 24
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:policies:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /readyz:
    get:
      tags:
        - Health
      summary: Check readiness
      description: Use this unauthenticated probe before routing traffic. It checks database readiness and returns not_ready while dependencies are unavailable.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
              example:
                status: ready
        "503":
          description: Service Unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Service Unavailable
                status: 503
                detail: not_ready
      security: []
  /roles/:
    get:
      tags:
        - Roles
      summary: List roles
      description: Lists platform or team roles ordered by role ID. `team_id` optionally filters by team; omitted or null-scoped roles are platform roles. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        team_id:
                          anyOf:
                            - type: string
                            - type: "null"
                      required:
                        - id
                        - name
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - id: 01J8Z3ROLE000000000000001
                    name: operator
                    team_id: 01J8Z3TEAM000000000000001
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
    post:
      tags:
        - Roles
      summary: Create a role
      description: Use to define a platform-wide or team-scoped role. team_id may be a ULID or JSON null.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                team_id: true
              required:
                - name
              type: object
            example:
              name: operator
              team_id: 01J8Z3TEAM000000000000001
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - id
                  - name
                type: object
              example:
                id: 01J8Z3ROLE000000000000001
                name: operator
                team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: the resource already exists
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
  /roles/{id}:
    delete:
      tags:
        - Roles
      summary: Delete a role
      description: Use to remove a role and all user, group, and team-baseline bindings. Affected users' permission versions are invalidated.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
    get:
      tags:
        - Roles
      summary: Get a role
      description: Use to retrieve one role and its scope before binding or changing permissions.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - id
                  - name
                type: object
              example:
                id: 01J8Z3ROLE000000000000001
                name: operator
                team_id: 01J8Z3TEAM000000000000001
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
    patch:
      tags:
        - Roles
      summary: Update a role
      description: Use to rename a role or change its team scope. At least one field is required; team-scoped administrators cannot change team_id outside their scope. Role changes invalidate every affected user's permission version, including users inheriting the role through a team baseline.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  anyOf:
                    - type: string
                    - type: "null"
                team_id: true
              type: object
            example:
              name: senior-operator
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  team_id:
                    anyOf:
                      - type: string
                      - type: "null"
                required:
                  - id
                  - name
                type: object
              example:
                id: 01J8Z3ROLE000000000000001
                name: senior-operator
                team_id: 01J8Z3TEAM000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
  /roles/{id}/permissions:
    get:
      tags:
        - Roles
      summary: List permissions on a role
      description: Lists the role's assigned permission keys in ascending order. Requires `iam:roles:any` or an applicable `iam:roles:team` grant for the role's team; reads do not require step-up authentication. See [REST pagination](/guide/pagination) for the shared cursor and response contract.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      type: string
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - orders:read:team
                  - orders:write:team
                next_cursor: orders:write:team
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
    put:
      tags:
        - Roles
      summary: Set permissions on a role
      description: Use to replace the complete permission set of a role. permission_keys is canonical; permissions is accepted as a legacy alias when permission_keys is absent. Every key must already be registered, including the optional ! deny prefix; applicable denies override matching allows across platform and team sources without role/source priority. A team-baseline deny therefore defeats a matching platform allow for an eligible member on that team's resource; users outside that team, including platform administrators without active membership, do not inherit the baseline deny and retain independent platform grants. Existing team baselines inherit the updated permissions, and affected users' permission versions are invalidated.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                permission_keys:
                  items:
                    type: string
                  type: array
                permissions:
                  items:
                    type: string
                  type: array
              type: object
            example:
              permission_keys:
                - orders:read:team
                - orders:update:own
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                permissions:
                  - orders:read:team
                  - orders:update:own
                role_id: 01J8Z3ROLE000000000000001
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Invalid Permission; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                permission must use resource:action:scope grammar:
                  value:
                    type: about:blank
                    title: Invalid Permission
                    status: 422
                    detail: permission must use resource:action:scope grammar
                'permission is not registered: orders:read:team':
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 422
                    detail: 'permission is not registered: orders:read:team'
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:roles:any
        team: iam:roles:team
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /scim/v2/Groups:
    get:
      tags:
        - SCIM
      summary: Report unsupported SCIM Groups
      description: Groups are not provisioned by this service. ResourceTypes lists User only; this endpoint returns a SCIM 501 error. The static SCIM bearer token is required.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "501":
          description: Not Implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Implemented
                status: 501
                detail: SCIM Groups provisioning is not supported
      security:
        - bearerAuth: []
  /scim/v2/ResourceTypes:
    get:
      tags:
        - SCIM
      summary: List supported SCIM resource types
      description: Lists User as the only supported resource type. Groups provisioning is unsupported and GET /scim/v2/Groups returns 501. The static SCIM bearer token is required.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  Resources:
                    items:
                      properties:
                        endpoint:
                          type: string
                        id:
                          type: string
                        meta:
                          properties:
                            resourceType:
                              type: string
                          required:
                            - resourceType
                          type: object
                        name:
                          type: string
                        schema:
                          type: string
                        schemas:
                          items:
                            type: string
                          type: array
                      required:
                        - schemas
                        - id
                        - name
                        - endpoint
                        - schema
                        - meta
                      type: object
                    type: array
                  itemsPerPage:
                    type: integer
                  schemas:
                    items:
                      type: string
                    type: array
                  startIndex:
                    type: integer
                  totalResults:
                    type: integer
                required:
                  - schemas
                  - totalResults
                  - startIndex
                  - itemsPerPage
                  - Resources
                type: object
              example:
                Resources:
                  - endpoint: /Users
                    id: User
                    meta:
                      resourceType: ResourceType
                    name: User
                    schema: urn:ietf:params:scim:schemas:core:2.0:User
                    schemas:
                      - urn:ietf:params:scim:schemas:core:2.0:ResourceType
                itemsPerPage: 1
                schemas:
                  - urn:ietf:params:scim:api:messages:2.0:ListResponse
                startIndex: 1
                totalResults: 1
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
      security:
        - bearerAuth: []
  /scim/v2/ServiceProviderConfig:
    get:
      tags:
        - SCIM
      summary: Read SCIM service capabilities
      description: Returns supported SCIM features. PATCH add/remove/replace operations for supported user attributes, including structured name sub-attributes, and userName equality filtering are supported; full user replacement is available with PUT. Bulk and sort are not supported. The static SCIM bearer token is required.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  authenticationSchemes:
                    items:
                      properties:
                        description:
                          type: string
                        name:
                          type: string
                        primary:
                          type: boolean
                        specUri:
                          type: string
                        type:
                          type: string
                      required:
                        - type
                        - name
                      type: object
                    type: array
                  bulk:
                    properties:
                      maxOperations:
                        type: integer
                      maxPayloadSize:
                        type: integer
                      supported:
                        type: boolean
                    required:
                      - supported
                    type: object
                  changePassword:
                    properties:
                      supported:
                        type: boolean
                    required:
                      - supported
                    type: object
                  etag:
                    properties:
                      supported:
                        type: boolean
                    required:
                      - supported
                    type: object
                  filter:
                    properties:
                      maxResults:
                        type: integer
                      supported:
                        type: boolean
                    required:
                      - supported
                    type: object
                  patch:
                    properties:
                      supported:
                        type: boolean
                    required:
                      - supported
                    type: object
                  schemas:
                    items:
                      type: string
                    type: array
                  sort:
                    properties:
                      supported:
                        type: boolean
                    required:
                      - supported
                    type: object
                required:
                  - schemas
                  - patch
                  - bulk
                  - filter
                  - changePassword
                  - sort
                  - etag
                  - authenticationSchemes
                type: object
              example:
                authenticationSchemes:
                  - description: Static bearer token authentication
                    name: SCIM Bearer Token
                    primary: true
                    specUri: https://www.rfc-editor.org/rfc/rfc6750
                    type: oauthbearertoken
                bulk:
                  supported: false
                changePassword:
                  supported: false
                etag:
                  supported: false
                filter:
                  maxResults: 1000
                  supported: true
                patch:
                  supported: true
                schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig
                sort:
                  supported: false
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
      security:
        - bearerAuth: []
  /scim/v2/Users:
    get:
      tags:
        - SCIM
      summary: List SCIM users
      description: Lists only externally identified users eligible for SCIM management, excluding erased users, service accounts, and users with effective IAM permissions. Uses SCIM startIndex/count pagination (startIndex is one-based; count defaults to 100 and may be zero). The only filter is userName eq "value"; count is capped at 1000. Invalid pagination and unsupported sort parameters return 400. Responses use application/scim+json and require the static SCIM bearer token.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  Resources:
                    items:
                      properties:
                        active:
                          type: boolean
                        displayName:
                          type: string
                        emails:
                          items:
                            properties:
                              primary:
                                type: boolean
                              type:
                                type: string
                              value:
                                type: string
                            required:
                              - value
                            type: object
                          type: array
                        externalId:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          type: string
                        meta:
                          properties:
                            created:
                              format: date-time
                              type: string
                            lastModified:
                              format: date-time
                              type: string
                            location:
                              type: string
                            resourceType:
                              type: string
                          required:
                            - resourceType
                            - created
                            - lastModified
                          type: object
                        name:
                          anyOf:
                            - properties:
                                familyName:
                                  type: string
                                formatted:
                                  type: string
                                givenName:
                                  type: string
                              type: object
                            - type: "null"
                        schemas:
                          items:
                            type: string
                          type: array
                        userName:
                          type: string
                      required:
                        - schemas
                        - id
                        - userName
                        - active
                        - meta
                      type: object
                    type: array
                  itemsPerPage:
                    type: integer
                  schemas:
                    items:
                      type: string
                    type: array
                  startIndex:
                    type: integer
                  totalResults:
                    type: integer
                required:
                  - schemas
                  - totalResults
                  - startIndex
                  - itemsPerPage
                  - Resources
                type: object
              example:
                Resources:
                  - active: true
                    id: 01J8Z3USER000000000000001
                    schemas:
                      - urn:ietf:params:scim:schemas:core:2.0:User
                    userName: alice
                itemsPerPage: 1
                schemas:
                  - urn:ietf:params:scim:api:messages:2.0:ListResponse
                startIndex: 1
                totalResults: 1
        "400":
          description: Invalid Filter
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Filter
                status: 400
                detail: only a userName eq string filter is supported
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: the SCIM request could not be completed
      security:
        - bearerAuth: []
    post:
      tags:
        - SCIM
      summary: Create a SCIM user
      description: Creates a user from userName, externalId, name/displayName, emails, and active. The schemas array must contain the core User schema URN. A non-empty externalId and userName are required. name.givenName and name.familyName are persisted and returned as a structured name with formatted derived from displayName. A supplied email must be a valid address and unique. A duplicate userName, externalId, or email returns 409. Include Idempotency-Key to replay a successful retry. The request and response use application/scim+json; the static SCIM bearer token is required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                active:
                  anyOf:
                    - type: boolean
                    - type: "null"
                displayName:
                  anyOf:
                    - type: string
                    - type: "null"
                emails:
                  items:
                    properties:
                      primary:
                        type: boolean
                      type:
                        type: string
                      value:
                        type: string
                    required:
                      - value
                    type: object
                  type: array
                externalId:
                  anyOf:
                    - type: string
                    - type: "null"
                name:
                  anyOf:
                    - properties:
                        familyName:
                          type: string
                        formatted:
                          type: string
                        givenName:
                          type: string
                      type: object
                    - type: "null"
                schemas:
                  items:
                    type: string
                  type: array
                userName:
                  type: string
              required:
                - userName
              type: object
            example:
              active: true
              emails:
                - primary: true
                  value: alice@example.test
              externalId: directory-123
              name:
                familyName: Example
                givenName: Alice
              schemas:
                - urn:ietf:params:scim:schemas:core:2.0:User
              userName: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  active:
                    type: boolean
                  displayName:
                    type: string
                  emails:
                    items:
                      properties:
                        primary:
                          type: boolean
                        type:
                          type: string
                        value:
                          type: string
                      required:
                        - value
                      type: object
                    type: array
                  externalId:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  meta:
                    properties:
                      created:
                        format: date-time
                        type: string
                      lastModified:
                        format: date-time
                        type: string
                      location:
                        type: string
                      resourceType:
                        type: string
                    required:
                      - resourceType
                      - created
                      - lastModified
                    type: object
                  name:
                    anyOf:
                      - properties:
                          familyName:
                            type: string
                          formatted:
                            type: string
                          givenName:
                            type: string
                        type: object
                      - type: "null"
                  schemas:
                    items:
                      type: string
                    type: array
                  userName:
                    type: string
                required:
                  - schemas
                  - id
                  - userName
                  - active
                  - meta
                type: object
              example:
                active: true
                displayName: Alice Example
                emails:
                  - primary: true
                    type: work
                    value: alice@example.test
                externalId: directory-123
                id: 01J8Z3USER000000000000001
                meta:
                  created: "2026-01-01T00:00:00Z"
                  lastModified: "2026-01-01T00:00:00Z"
                  location: /scim/v2/Users/01J8Z3USER000000000000001
                  resourceType: User
                schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                userName: alice
        "400":
          description: Invalid Value
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Value
                status: 400
                detail: the schemas array or userName/externalId is invalid, or email is invalid
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "409":
          description: Uniqueness Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Uniqueness Conflict
                status: 409
                detail: userName, externalId, or email already exists
        "415":
          description: Unsupported Media Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unsupported Media Type
                status: 415
                detail: Content-Type must be application/scim+json
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: the SCIM request could not be completed
      security:
        - bearerAuth: []
  /scim/v2/Users/{id}:
    delete:
      tags:
        - SCIM
      summary: Disable a SCIM user
      description: Soft-deletes an eligible SCIM user by setting active to false and marking the disable as SCIM-owned so a later SCIM activation is allowed. Erased, service-account, and effective-IAM targets are protected; the user record remains readable as disabled only while it remains eligible. Sessions are revoked, permissions invalidated, lifecycle/audit records appended, and the endpoint returns no body. Repeated DELETE on an already-disabled user returns 204 without new audit or lifecycle rows. The static SCIM bearer token is required.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: the SCIM target is protected
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested user was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: the SCIM request could not be completed
      security:
        - bearerAuth: []
    get:
      tags:
        - SCIM
      summary: Read a SCIM user
      description: Returns one SCIM User by the service-issued id. The name attribute is a structured object with formatted, givenName, and familyName so values round-trip losslessly; formatted always matches displayName. Users without externalId, erased users, service accounts, and users with effective IAM permissions are reported as not found. The response uses application/scim+json and requires the static SCIM bearer token.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  active:
                    type: boolean
                  displayName:
                    type: string
                  emails:
                    items:
                      properties:
                        primary:
                          type: boolean
                        type:
                          type: string
                        value:
                          type: string
                      required:
                        - value
                      type: object
                    type: array
                  externalId:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  meta:
                    properties:
                      created:
                        format: date-time
                        type: string
                      lastModified:
                        format: date-time
                        type: string
                      location:
                        type: string
                      resourceType:
                        type: string
                    required:
                      - resourceType
                      - created
                      - lastModified
                    type: object
                  name:
                    anyOf:
                      - properties:
                          familyName:
                            type: string
                          formatted:
                            type: string
                          givenName:
                            type: string
                        type: object
                      - type: "null"
                  schemas:
                    items:
                      type: string
                    type: array
                  userName:
                    type: string
                required:
                  - schemas
                  - id
                  - userName
                  - active
                  - meta
                type: object
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested user was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: the SCIM request could not be completed
      security:
        - bearerAuth: []
    patch:
      tags:
        - SCIM
      summary: Update a SCIM user
      description: Applies RFC 7644 add/remove/replace operations for active, name (including dotted name.formatted, name.givenName, and name.familyName paths and pathless attribute keys), displayName, and emails, including filtered paths such as emails[type eq "work"].value. The schemas array must contain the PatchOp URN. Changed emails must be valid and unique. Service accounts and users with effective IAM permissions remain protected. Only users disabled through SCIM can be activated; administrators disabling a user clear the SCIM marker, so admin-disabled, pending, and invited users return 403 with a mutability hint. No-op operations are accepted without appending audit or lifecycle rows. The request and response use application/scim+json; the static SCIM bearer token is required.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                Operations:
                  items:
                    properties:
                      op:
                        type: string
                      path:
                        type: string
                      value: true
                    required:
                      - op
                      - value
                    type: object
                  type: array
                schemas:
                  items:
                    type: string
                  type: array
              required:
                - Operations
              type: object
            example:
              operations:
                - op: replace
                  path: active
                  value: false
                - op: add
                  path: emails[type eq "work"].value
                  value: alice@example.test
              schemas:
                - urn:ietf:params:scim:api:messages:2.0:PatchOp
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  active:
                    type: boolean
                  displayName:
                    type: string
                  emails:
                    items:
                      properties:
                        primary:
                          type: boolean
                        type:
                          type: string
                        value:
                          type: string
                      required:
                        - value
                      type: object
                    type: array
                  externalId:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  meta:
                    properties:
                      created:
                        format: date-time
                        type: string
                      lastModified:
                        format: date-time
                        type: string
                      location:
                        type: string
                      resourceType:
                        type: string
                    required:
                      - resourceType
                      - created
                      - lastModified
                    type: object
                  name:
                    anyOf:
                      - properties:
                          familyName:
                            type: string
                          formatted:
                            type: string
                          givenName:
                            type: string
                        type: object
                      - type: "null"
                  schemas:
                    items:
                      type: string
                    type: array
                  userName:
                    type: string
                required:
                  - schemas
                  - id
                  - userName
                  - active
                  - meta
                type: object
        "400":
          description: Invalid Patch
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Patch
                status: 400
                detail: the schemas array, PATCH path, or value is invalid, or the email address is invalid
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: the SCIM target is protected or cannot be activated
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested user was not found
        "409":
          description: Uniqueness Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Uniqueness Conflict
                status: 409
                detail: email is already in use
        "415":
          description: Unsupported Media Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unsupported Media Type
                status: 415
                detail: Content-Type must be application/scim+json
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: the SCIM request could not be completed
      security:
        - bearerAuth: []
    put:
      tags:
        - SCIM
      summary: Replace a SCIM user
      description: Replaces the SCIM user's writable profile fields. The schemas array must contain the core User schema URN. userName is required; omitted displayName, name sub-attributes, and emails are cleared, and active defaults to true unless explicitly false. A non-empty externalId replaces the client-owned identifier; if omitted it is preserved and it cannot be cleared. Email values must be valid and unique. Only eligible users without effective IAM permissions or service credentials may be changed. Activation is allowed only for users disabled through SCIM (scim_disabled); administrators disabling a user clear that marker, so admin-disabled and pending or invited users cannot be activated through SCIM.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                active:
                  anyOf:
                    - type: boolean
                    - type: "null"
                displayName:
                  anyOf:
                    - type: string
                    - type: "null"
                emails:
                  items:
                    properties:
                      primary:
                        type: boolean
                      type:
                        type: string
                      value:
                        type: string
                    required:
                      - value
                    type: object
                  type: array
                externalId:
                  anyOf:
                    - type: string
                    - type: "null"
                name:
                  anyOf:
                    - properties:
                        familyName:
                          type: string
                        formatted:
                          type: string
                        givenName:
                          type: string
                      type: object
                    - type: "null"
                schemas:
                  items:
                    type: string
                  type: array
                userName:
                  type: string
              required:
                - userName
              type: object
            example:
              active: true
              emails:
                - primary: true
                  type: work
                  value: alice@example.test
              externalId: directory-123
              userName: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  active:
                    type: boolean
                  displayName:
                    type: string
                  emails:
                    items:
                      properties:
                        primary:
                          type: boolean
                        type:
                          type: string
                        value:
                          type: string
                      required:
                        - value
                      type: object
                    type: array
                  externalId:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                  meta:
                    properties:
                      created:
                        format: date-time
                        type: string
                      lastModified:
                        format: date-time
                        type: string
                      location:
                        type: string
                      resourceType:
                        type: string
                    required:
                      - resourceType
                      - created
                      - lastModified
                    type: object
                  name:
                    anyOf:
                      - properties:
                          familyName:
                            type: string
                          formatted:
                            type: string
                          givenName:
                            type: string
                        type: object
                      - type: "null"
                  schemas:
                    items:
                      type: string
                    type: array
                  userName:
                    type: string
                required:
                  - schemas
                  - id
                  - userName
                  - active
                  - meta
                type: object
        "400":
          description: Invalid Value
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Value
                status: 400
                detail: the schemas array, userName, externalId, or email is invalid
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: a valid SCIM bearer token is required
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: the SCIM target is protected or cannot be activated
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested user was not found
        "409":
          description: Uniqueness Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Uniqueness Conflict
                status: 409
                detail: userName, externalId, or email already exists
        "415":
          description: Unsupported Media Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unsupported Media Type
                status: 415
                detail: Content-Type must be application/scim+json
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: the SCIM request could not be completed
      security:
        - bearerAuth: []
  /teams/:
    get:
      tags:
        - Teams
      summary: List teams
      description: Use from an administrator console to list teams, ordered by ascending team ID. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                        slug:
                          type: string
                        status:
                          type: string
                      required:
                        - id
                        - slug
                        - name
                        - status
                        - created_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    id: 01J8Z3TEAM000000000000001
                    name: Acme
                    slug: acme
                    status: active
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:teams:any
        team: iam:teams:team
    post:
      tags:
        - Teams
      summary: Create a team
      description: Use when provisioning a new tenant or workspace. Slug and name are required; status defaults to active.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                slug:
                  type: string
                status:
                  type: string
              required:
                - slug
                - name
              type: object
            example:
              name: Acme
              slug: acme
              status: active
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  status:
                    type: string
                required:
                  - id
                  - slug
                  - name
                  - status
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3TEAM000000000000001
                name: Acme
                slug: acme
                status: active
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: the resource already exists
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:teams:any
        team: iam:teams:team
  /teams/{id}:
    delete:
      tags:
        - Teams
      summary: Delete a team
      description: Use to remove a team and its dependent administrative records. The operation invalidates affected permission versions and is audited.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:teams:any
        team: iam:teams:team
    get:
      tags:
        - Teams
      summary: Get a team
      description: Use to retrieve one team by ULID for an administrative view or downstream provisioning step.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  status:
                    type: string
                required:
                  - id
                  - slug
                  - name
                  - status
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3TEAM000000000000001
                name: Acme
                slug: acme
                status: active
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:teams:any
        team: iam:teams:team
    patch:
      tags:
        - Teams
      summary: Update a team
      description: Use to rename or change a team's slug/status. At least one field is required; status must be active or disabled. Disabling a team suppresses its scoped grants and invalidates permission versions for affected members; independent platform grants remain available.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  anyOf:
                    - type: string
                    - type: "null"
                slug:
                  anyOf:
                    - type: string
                    - type: "null"
                status:
                  anyOf:
                    - type: string
                    - type: "null"
              type: object
            example:
              name: Acme Europe
              status: active
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  id:
                    type: string
                  name:
                    type: string
                  slug:
                    type: string
                  status:
                    type: string
                required:
                  - id
                  - slug
                  - name
                  - status
                  - created_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                id: 01J8Z3TEAM000000000000001
                name: Acme Europe
                slug: acme
                status: active
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:teams:any
        team: iam:teams:team
  /users/:
    get:
      tags:
        - Users
      summary: List users
      description: Use from an administrator console to list all users, ordered by ascending user ID. Cursors are user ULIDs. See [REST pagination](/guide/pagination) for the shared collection contract.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        approved_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        approved_by:
                          anyOf:
                            - type: string
                            - type: "null"
                        created_at:
                          format: date-time
                          type: string
                        display_name:
                          type: string
                        email:
                          anyOf:
                            - type: string
                            - type: "null"
                        email_verified_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        failed_logins:
                          type: integer
                        id:
                          type: string
                        locked_until:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                        perm_ver:
                          type: integer
                        status:
                          type: string
                        updated_at:
                          format: date-time
                          type: string
                        username:
                          type: string
                      required:
                        - id
                        - username
                        - display_name
                        - status
                        - perm_ver
                        - failed_logins
                        - created_at
                        - updated_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    display_name: Alice Example
                    email: alice@example.test
                    email_verified_at: "2026-01-01T00:00:00Z"
                    failed_logins: 0
                    id: 01J8Z3USER000000000000001
                    perm_ver: 3
                    status: active
                    updated_at: "2026-01-01T00:00:00Z"
                    username: alice
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
    post:
      tags:
        - Users
      summary: Create a user
      description: Use from an administrator or provisioning workflow to create an active user. Password and initial_password are optional; password wins when both are supplied.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                display_name:
                  type: string
                email:
                  anyOf:
                    - type: string
                    - type: "null"
                initial_password:
                  type: string
                password:
                  type: string
                username:
                  type: string
              required:
                - username
              type: object
            example:
              display_name: Alice Example
              email: alice@example.test
              password: AtLeastTwelve1
              username: alice
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  approved_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  approved_by:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  failed_logins:
                    type: integer
                  id:
                    type: string
                  locked_until:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  perm_ver:
                    type: integer
                  status:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - perm_ver
                  - failed_logins
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Example
                email: alice@example.test
                email_verified_at: "2026-01-01T00:00:00Z"
                failed_logins: 0
                id: 01J8Z3USER000000000000001
                perm_ver: 3
                status: active
                updated_at: "2026-01-01T00:00:00Z"
                username: alice
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "409":
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Conflict
                status: 409
                detail: the resource already exists
        "422":
          description: Weak Password
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Weak Password
                status: 422
                detail: weak_password
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
  /users/batch:
    post:
      tags:
        - Users
      summary: Enable or disable users in batches
      description: Use for administrative bulk status changes. Up to 500 IDs are processed independently; each result records success or invalid_id, not_found, or operation_failed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                ids:
                  items:
                    type: string
                  type: array
                op:
                  type: string
              required:
                - op
              type: object
            example:
              ids:
                - 01J8Z3USER000000000000001
                - 01J8Z3USER000000000000002
              op: disable
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                results:
                  - id: 01J8Z3USER000000000000001
                    ok: true
                  - error: not_found
                    id: 01J8Z3USER000000000000002
                    ok: false
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "422":
          description: Invalid Operation; Too Many Items
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                op must be disable or enable:
                  value:
                    type: about:blank
                    title: Invalid Operation
                    status: 422
                    detail: op must be disable or enable
                a maximum of 500 ids is allowed:
                  value:
                    type: about:blank
                    title: Too Many Items
                    status: 422
                    detail: a maximum of 500 ids is allowed
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: When `op` is `disable`, requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. `enable` does not require fresh authentication.
  /users/import:
    post:
      tags:
        - Users
      summary: Import users from CSV
      description: Use for bulk provisioning from an administrator export. Send text/csv with exactly username,email,display_name,password columns and at most 500 data rows; each row is reported independently.
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                results:
                  - id: 01J8Z3USER000000000000001
                    ok: true
                    row: 2
                    username: alice
                  - error: weak_password
                    ok: false
                    row: 3
                    username: bob
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "415":
          description: Unsupported Media Type
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unsupported Media Type
                status: 415
                detail: Content-Type must be text/csv
        "422":
          description: Invalid CSV
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid CSV
                status: 422
                detail: CSV header must be username,email,display_name,password
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
  /users/{id}:
    delete:
      tags:
        - Users
      summary: Delete a user
      description: Use for an administrative hard deletion. Cascaded records are removed and the operation is audited; prefer account erasure for self-service privacy requests.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
    get:
      tags:
        - Users
      summary: Get a user
      description: Use to retrieve one administrative user record by ULID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  approved_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  approved_by:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  failed_logins:
                    type: integer
                  id:
                    type: string
                  locked_until:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  perm_ver:
                    type: integer
                  status:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - perm_ver
                  - failed_logins
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Example
                email: alice@example.test
                email_verified_at: "2026-01-01T00:00:00Z"
                failed_logins: 0
                id: 01J8Z3USER000000000000001
                perm_ver: 3
                status: active
                updated_at: "2026-01-01T00:00:00Z"
                username: alice
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
    patch:
      tags:
        - Users
      summary: Update a user
      description: Use for administrative profile or status changes. At least one of username, email, display_name, and status is required; status may be active or disabled.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                email:
                  anyOf:
                    - type: string
                    - type: "null"
                status:
                  anyOf:
                    - type: string
                    - type: "null"
                username:
                  anyOf:
                    - type: string
                    - type: "null"
              type: object
            example:
              display_name: Alice Smith
              status: active
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  approved_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  approved_by:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  failed_logins:
                    type: integer
                  id:
                    type: string
                  locked_until:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  perm_ver:
                    type: integer
                  status:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - perm_ver
                  - failed_logins
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Smith
                email: alice@example.test
                failed_logins: 0
                id: 01J8Z3USER000000000000001
                perm_ver: 3
                status: active
                updated_at: "2026-01-01T00:00:00Z"
                username: alice
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: request body must be valid JSON
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Setting a non-null email or disabling a user requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Other profile changes do not require fresh authentication.
  /users/{id}/approve:
    post:
      tags:
        - Users
      summary: Approve a pending user
      description: Use in approval registration mode after the user has verified email. The administrator's user bearer is recorded as approver; unverified accounts return email_not_verified.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  approved_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  approved_by:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  failed_logins:
                    type: integer
                  id:
                    type: string
                  locked_until:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  perm_ver:
                    type: integer
                  status:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - perm_ver
                  - failed_logins
                  - created_at
                  - updated_at
                type: object
              example:
                approved_at: "2026-01-02T00:00:00Z"
                approved_by: 01J8Z3ADMIN000000000000001
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Example
                email: alice@example.test
                email_verified_at: "2026-01-01T00:00:00Z"
                failed_logins: 0
                id: 01J8Z3USER000000000000001
                perm_ver: 1
                status: active
                updated_at: "2026-01-02T00:00:00Z"
                username: alice
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 422
                detail: email_not_verified
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /users/{id}/credentials:
    get:
      tags:
        - Users
      summary: List user credential metadata
      description: Lists every credential kind for the path user in ascending `kind` order. `kind` is unique per user and is the cursor key. The response includes only `kind`, `created_at`, optional `rotated_at`, and `must_change`; hashes, secrets, tokens, and credential material are never returned. See [REST collection pagination](/guide/pagination) for the shared collection contract.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        kind:
                          type: string
                        must_change:
                          type: boolean
                        rotated_at:
                          anyOf:
                            - format: date-time
                              type: string
                            - type: "null"
                      required:
                        - kind
                        - created_at
                        - must_change
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    kind: service
                    must_change: false
                    rotated_at: "2026-02-01T00:00:00Z"
                next_cursor: ""
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: limit must be a positive integer
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires `iam:users:any`; reads do not require step-up authentication.
    post:
      tags:
        - Users
      summary: Create or rotate a user credential
      description: Use to provision a password credential or a service credential. Service secrets are generated and returned exactly once; password hashes are never returned.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                kind:
                  type: string
                password:
                  type: string
              required:
                - kind
              type: object
            example:
              kind: password
              password: AtLeastTwelve1
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
              example:
                kind: password
                user_id: 01J8Z3USER000000000000001
                username: alice
        "400":
          description: Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Invalid Request
                status: 400
                detail: kind must be password or service
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "422":
          description: Weak Password
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Weak Password
                status: 422
                detail: weak_password
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /users/{id}/disable:
    post:
      tags:
        - Users
      summary: Disable a user
      description: Use as a dedicated administrative lock switch. It resets lockout state, revokes sessions, invalidates permissions, and emits the same lifecycle events as a disabled status update.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  approved_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  approved_by:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    format: date-time
                    type: string
                  display_name:
                    type: string
                  email:
                    anyOf:
                      - type: string
                      - type: "null"
                  email_verified_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  failed_logins:
                    type: integer
                  id:
                    type: string
                  locked_until:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  perm_ver:
                    type: integer
                  status:
                    type: string
                  updated_at:
                    format: date-time
                    type: string
                  username:
                    type: string
                required:
                  - id
                  - username
                  - display_name
                  - status
                  - perm_ver
                  - failed_logins
                  - created_at
                  - updated_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                display_name: Alice Example
                email: alice@example.test
                failed_logins: 0
                id: 01J8Z3USER000000000000001
                perm_ver: 4
                status: disabled
                updated_at: "2026-01-01T00:00:00Z"
                username: alice
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
  /users/{id}/invitation:
    get:
      tags:
        - Users
      summary: Get a user's invitation metadata
      description: Returns the latest persisted invitation row's timestamps and the user's actual stored status in `user_status`. A user without a persisted invitation row receives the generic not-found response. This does not report notification delivery or infer an accepted state.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  expires_at:
                    format: date-time
                    type: string
                  used_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                  user_status:
                    type: string
                required:
                  - user_status
                  - created_at
                  - expires_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                expires_at: "2026-01-08T00:00:00Z"
                user_status: invited
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires `iam:users:any`; reads do not require step-up authentication.
  /users/{id}/password-policy:
    get:
      tags:
        - Users
      summary: Get a user's effective password policy
      description: Use to inspect the resolved password requirements for one administrative user. The response contains only the merged policy.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  breach_check:
                    type: boolean
                  history_count:
                    type: integer
                  min_length:
                    type: integer
                  require_digit:
                    type: boolean
                  require_letter:
                    type: boolean
                  require_lower:
                    type: boolean
                  require_symbol:
                    type: boolean
                  require_upper:
                    type: boolean
                required:
                  - min_length
                  - require_letter
                  - require_upper
                  - require_lower
                  - require_digit
                  - require_symbol
                  - history_count
                  - breach_check
                type: object
              example:
                breach_check: true
                history_count: 5
                min_length: 12
                require_digit: true
                require_letter: true
                require_lower: false
                require_symbol: false
                require_upper: false
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
  /users/{id}/sessions:
    delete:
      tags:
        - Sessions
      summary: Revoke every session for a user
      description: Use for incident response or after an administrative password reset. It revokes all refresh sessions for the target user and returns no body.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:sessions:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
    get:
      tags:
        - Sessions
      summary: List a user's sessions
      description: Lists active, unexpired refresh sessions for the path user, ordered by `created_at` ascending and session ID ascending. Rows include `created_at`, `last_active_at`, and `expires_at`; client metadata and refresh tokens are never returned. The cursor is an opaque composite of the full ordering key. See [REST pagination](/guide/pagination) for the shared collection contract.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  items:
                    items:
                      properties:
                        created_at:
                          format: date-time
                          type: string
                        expires_at:
                          format: date-time
                          type: string
                        id:
                          type: string
                        last_active_at:
                          format: date-time
                          type: string
                      required:
                        - id
                        - created_at
                        - last_active_at
                        - expires_at
                      type: object
                    type: array
                  next_cursor:
                    type: string
                required:
                  - items
                  - next_cursor
                type: object
              example:
                items:
                  - created_at: "2026-01-01T00:00:00Z"
                    expires_at: "2026-01-31T00:00:00Z"
                    id: 8d7e5b3a0f6f4e1d...
                    last_active_at: "2026-01-02T12:00:00Z"
                next_cursor: ""
        "400":
          description: Invalid Request; Invalid Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                limit must be a positive integer:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: limit must be a positive integer
                cursor is not a valid session cursor:
                  value:
                    type: about:blank
                    title: Invalid Request
                    status: 400
                    detail: cursor is not a valid session cursor
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:sessions:any
  /users/{id}/sessions/{sid}:
    delete:
      tags:
        - Sessions
      summary: Revoke one user's session
      description: Use to revoke one device session during security review. The session must belong to the path user; foreign IDs return not_found.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: sid
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:sessions:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
    get:
      tags:
        - Sessions
      summary: Get a user's session metadata
      description: Use to inspect one session owned by the path user. Unknown user/session pairs and sessions belonging to another user return the same generic not-found response. Retained revoked or expired sessions remain readable. The response contains only the session ID, timestamps, and optional revocation metadata; it never returns refresh tokens or client metadata.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: sid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  created_at:
                    format: date-time
                    type: string
                  expires_at:
                    format: date-time
                    type: string
                  id:
                    type: string
                  last_active_at:
                    format: date-time
                    type: string
                  revoke_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  revoked_at:
                    anyOf:
                      - format: date-time
                        type: string
                      - type: "null"
                required:
                  - id
                  - created_at
                  - last_active_at
                  - expires_at
                type: object
              example:
                created_at: "2026-01-01T00:00:00Z"
                expires_at: "2026-01-31T00:00:00Z"
                id: 8d7e5b3a0f6f4e1d...
                last_active_at: "2026-01-02T12:00:00Z"
                revoke_reason: logout
                revoked_at: "2026-01-03T09:00:00Z"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Forbidden
                status: 403
                detail: insufficient_permissions
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:sessions:any
        note: Requires `iam:sessions:any`; reads do not require step-up authentication.
  /users/{id}/totp:
    delete:
      tags:
        - Users
      summary: Reset a user's TOTP
      description: Use for administrative recovery when a user loses MFA access. It deletes active, pending, and backup-code credentials without requiring the user's TOTP code.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: authentication failed
        "403":
          description: Forbidden; Step-up Required
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                insufficient_permissions:
                  value:
                    type: about:blank
                    title: Forbidden
                    status: 403
                    detail: insufficient_permissions
                step_up_required:
                  value:
                    type: about:blank
                    title: Step-up Required
                    status: 403
                    detail: step_up_required
        "404":
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Not Found
                status: 404
                detail: the requested resource was not found
        "500":
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: authentication service unavailable
      security:
        - bearerAuth: []
      x-teamusers-permission:
        any: iam:users:any
        note: Requires a user bearer with positive `auth_time` or `step_up_time` no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 `step_up_required`.
components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      required:
        - type
        - title
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: EdDSA JWT
