# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Dot Auth API
  version: 1.0.0
extends: openapi/dotcms-dotauth-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 15
- target: $.paths['/api/v1/dotauth/oauth/exchange'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange an OIDC ID token for a session-ref
      effect: write
      questions:
      - How do I turn an OIDC id_token into a dotCMS session for a headless app?
      - Will a user be created automatically if they sign in via token exchange for the first time?
      - Can I control how many days the returned session-ref stays valid?
      instructions:
      - text: Exchange ID token {idToken} with nonce {nonce} for a dotAuth session-ref.
        slots:
          idToken: requestBody.idToken
          nonce: requestBody.nonce
      - text: Trade id_token {idToken} (nonce {nonce}) for a session-ref valid for {expirationDays} days.
        slots:
          idToken: requestBody.idToken
          nonce: requestBody.nonce
          expirationDays: requestBody.expirationDays
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/oauth/exchange'].options
  update:
    x-apievangelist-phrasing:
      intent: Preflight the token exchange endpoint for CORS
      effect: read
      questions:
      - Does the OIDC token exchange endpoint answer CORS preflight requests?
      - Which options does a browser see before calling the dotAuth exchange?
      instructions:
      - text: Send a CORS preflight OPTIONS request to the token exchange endpoint.
      - text: Check the preflight response for the dotAuth OIDC exchange.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/sites/{hostId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a site's SSO configuration
      effect: read
      questions:
      - What OAuth or SAML settings are stored for a site?
      - Is a site inheriting its single sign-on setup from the system default?
      instructions:
      - text: Show the dotAuth SSO configuration for site {hostId}.
        slots:
          hostId: path.hostId
      - text: Get the global default SSO config stored under {hostId}, with secrets masked.
        slots:
          hostId: path.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/sites/{hostId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Save a site's SSO configuration
      effect: write
      questions:
      - How do I configure OAuth or SAML sign-in for a specific site?
      - Does saving SAML settings for a site remove its OAuth settings?
      instructions:
      - text: Save {protocol} SSO settings {values} for site {hostId}.
        slots:
          protocol: requestBody.protocol
          values: requestBody.values
          hostId: path.hostId
      - text: Upsert the dotAuth configuration values {values} on host {hostId}.
        slots:
          values: requestBody.values
          hostId: path.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/sites/{hostId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear a site's SSO configuration
      effect: destructive
      questions:
      - How do I remove single sign-on settings from a site?
      - What happens to a site's SSO after I clear its own configuration?
      instructions:
      - text: Clear the OAuth and SAML configuration for site {hostId}.
        slots:
          hostId: path.hostId
      - text: Delete dotAuth secrets on host {hostId} so it falls back to the system default.
        slots:
          hostId: path.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/headless'].put
  update:
    x-apievangelist-phrasing:
      intent: Save the headless token-exchange configuration
      effect: write
      questions:
      - Where do I configure headless token exchange for the whole system?
      - Is the headless exchange setting per site or system-wide?
      instructions:
      - text: Save the system-wide headless token-exchange configuration.
      - text: Update the headless dotAuth settings on the system host.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/headless'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear the headless token-exchange configuration
      effect: destructive
      questions:
      - How do I turn off headless token exchange?
      - Will clearing the headless config also wipe my SSO settings?
      instructions:
      - text: Delete the headless token-exchange configuration.
      - text: Remove system-level headless dotAuth settings, leaving SSO untouched.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/discover/oidc'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch an OIDC discovery document
      effect: read
      questions:
      - Can dotCMS read an identity provider's openid-configuration to fill in issuer and JWKS?
      - How do I pull endpoints and algorithms from an OIDC well-known URL?
      instructions:
      - text: Fetch and parse the OIDC discovery document at this .well-known URL.
      - text: Look up the issuer, endpoints and JWKS from my provider's openid-configuration.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export all dotAuth secrets
      effect: read
      questions:
      - How do I back up my OAuth, SAML and headless sign-in secrets?
      - Can I export dotAuth settings to move them to another environment?
      instructions:
      - text: Export all dotAuth AppSecrets to an encrypted file.
      - text: Create an encrypted export of the OAuth, SAML and headless secrets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/fetch/saml-metadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch SAML IdP metadata from a URL
      effect: read
      questions:
      - Can dotCMS download my identity provider's SAML metadata XML for review?
      - How do I pull IdP metadata from its URL before saving SAML settings?
      instructions:
      - text: Fetch the SAML IdP metadata XML from this metadata URL.
      - text: Retrieve my identity provider's SAML metadata so I can review it.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/saml/metadata/{hostId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a site's SAML SP metadata
      effect: read
      questions:
      - Where do I get the service provider metadata XML to give my SAML IdP?
      - What entity ID and ACS URL does a site advertise for SAML?
      instructions:
      - text: Download the SAML service provider metadata for site {hostId}.
        slots:
          hostId: path.hostId
      - text: Generate SP metadata XML for host {hostId}.
        slots:
          hostId: path.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import dotAuth secrets
      effect: write
      questions:
      - How do I restore dotAuth sign-in settings from an export file?
      - Can I import only OAuth, SAML and headless secrets from an encrypted file?
      instructions:
      - text: Import dotAuth AppSecrets from this encrypted export file.
      - text: Restore OAuth, SAML and headless secrets from my dotAuth export.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/sites'].get
  update:
    x-apievangelist-phrasing:
      intent: List sites with their SSO status
      effect: read
      questions:
      - Which sites have their own SSO configured and which inherit the default?
      - Are any of my sites left without sign-on configuration?
      instructions:
      - text: List every site with its dotAuth SSO status.
      - text: Show which sites are configured, inherited or unconfigured for SSO.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/sessionrefs/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke all session-refs
      effect: destructive
      questions:
      - How do I invalidate every headless session-ref at once?
      - Does flushing session-refs log out existing browser sessions?
      instructions:
      - text: Revoke all dotAuth session-refs.
      - text: Flush the dotAuth session-ref cache.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/dotauth/oauth/session'].delete
  update:
    x-apievangelist-phrasing:
      intent: Sign out a session-ref
      effect: destructive
      questions:
      - How do I end my own headless session-ref on sign-out?
      - Is it safe to call sign-out when the session-ref is already gone?
      instructions:
      - text: Invalidate my current dotAuth session-ref.
      - text: Sign me out by removing the session-ref in my bearer header.
      method: generated
      generated: '2026-09-26'