API Evangelist conversational phrasing for Clerk Frontend OAuth2 Identity Provider API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Clerk Frontend OAuth2 Identity Provider API
  version: 1.0.0
extends: openapi/clerk-com-oauth2-identity-provider-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: 10
- target: $.paths['/oauth/authorize'].get
  update:
    x-apievangelist-phrasing:
      intent: Start an OAuth2 authorization via GET redirect
      effect: read
      questions:
      - How do I send a user to the authorization endpoint to get an OAuth code using a GET link?
      - Does the authorize URL support PKCE code challenges as query parameters?
      instructions:
      - text: Build a GET authorize request for client {client_id} with response type {response_type}.
        slots:
          client_id: query.client_id
          response_type: query.response_type
      - text: Request authorization in the query string for client {client_id}, type {response_type}, scope {scope}, redirect {redirect_uri}.
        slots:
          client_id: query.client_id
          response_type: query.response_type
          scope: query.scope
          redirect_uri: query.redirect_uri
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/authorize'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an OAuth2 authorization via form POST
      effect: write
      questions:
      - Can I post the authorization request as a form body instead of query parameters?
      - How do I submit an OAuth2 authorize request with a POST body including a nonce?
      instructions:
      - text: POST an authorization request for client {client_id} with response type {response_type}.
        slots:
          client_id: requestBody.client_id
          response_type: requestBody.response_type
      - text: Submit a form-posted authorize request for {client_id}, type {response_type}, state {state}.
        slots:
          client_id: requestBody.client_id
          response_type: requestBody.response_type
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/register'].post
  update:
    x-apievangelist-phrasing:
      intent: Dynamically register an OAuth client
      effect: write
      questions:
      - How can an app register itself as an OAuth client without manual setup?
      - Does the identity provider support RFC 7591 dynamic client registration?
      instructions:
      - text: Register an OAuth client with redirect URIs {redirect_uris}.
        slots:
          redirect_uris: requestBody.redirect_uris
      - text: Register OAuth client {client_name} with redirect URIs {redirect_uris} and scope {scope}.
        slots:
          client_name: requestBody.client_name
          redirect_uris: requestBody.redirect_uris
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange a code or refresh token for tokens
      effect: write
      questions:
      - How do I trade an authorization code for access and ID tokens?
      - Can I use a refresh token grant to get a new access token?
      instructions:
      - text: Exchange authorization code {code} for tokens with grant type {grant_type}.
        slots:
          code: requestBody.code
          grant_type: requestBody.grant_type
      - text: Get a new access token using refresh token {refresh_token} (grant {grant_type}).
        slots:
          refresh_token: requestBody.refresh_token
          grant_type: requestBody.grant_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/userinfo'].get
  update:
    x-apievangelist-phrasing:
      intent: Get user info with an access token via GET
      effect: read
      questions:
      - How do I fetch the signed-in user's profile claims with an OAuth access token using GET?
      - Which endpoint returns OIDC userinfo on a plain GET request?
      instructions:
      - text: Get the userinfo for my OAuth access token with a GET request.
      - text: Fetch OIDC user claims via GET.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/userinfo'].post
  update:
    x-apievangelist-phrasing:
      intent: Get user info with an access token via POST
      effect: read
      questions:
      - Can I request OIDC userinfo with a POST instead of a GET?
      - Which userinfo variant accepts a POST request from my OAuth client?
      instructions:
      - text: POST my access token to the userinfo endpoint to get my profile claims.
      - text: Use the POST variant of userinfo to fetch OIDC claims.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/token_info'].post
  update:
    x-apievangelist-phrasing:
      intent: Introspect an access or refresh token
      effect: read
      questions:
      - How do I check whether an OAuth token is still active and what scopes it has?
      - Can I introspect a refresh token as well as an access token?
      instructions:
      - text: Introspect token {token}.
        slots:
          token: requestBody.token
      - text: Get info for token {token} with hint {token_type_hint}.
        slots:
          token: requestBody.token
          token_type_hint: requestBody.token_type_hint
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth/token/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke an OAuth2 token
      effect: destructive
      questions:
      - How do I invalidate an OAuth access or refresh token that was issued to my app?
      - Do confidential clients need Basic auth to revoke a token?
      instructions:
      - text: Revoke OAuth token {token}.
        slots:
          token: requestBody.token
      - text: Revoke token {token} as a {token_type_hint}.
        slots:
          token: requestBody.token
          token_type_hint: requestBody.token_type_hint
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/oauth/consent/{client_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get consent scopes for an OAuth app
      effect: read
      questions:
      - What scopes will a user be asked to consent to for an OAuth application?
      - Can I restrict the consent info to only the scopes being requested?
      instructions:
      - text: Show the consent scopes for OAuth client {client_id}.
        slots:
          client_id: path.client_id
      - text: Get consent information for client {client_id} limited to scope {scope}.
        slots:
          client_id: path.client_id
          scope: query.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/me/oauth/consent/{client_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a user's OAuth consent decision
      effect: write
      questions:
      - How do I build a custom consent screen that records whether the user approved?
      - Can a user grant consent to an OAuth app on behalf of an organization?
      instructions:
      - text: Submit consent {consented} for OAuth client {client_id}.
        slots:
          consented: requestBody.consented
          client_id: path.client_id
      - text: Approve client {client_id} for organization {organization_id} (consented {consented}).
        slots:
          client_id: path.client_id
          organization_id: requestBody.organization_id
          consented: requestBody.consented
      method: generated
      generated: '2026-09-26'