# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Appwrite Oauth2 API
  version: 1.0.0
extends: openapi/appwrite-oauth2-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: 14
- target: $.paths['/oauth2/{project_id}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a consent grant for an OAuth2 app
      effect: write
      questions:
      - How does my consent screen approve an app's authorization request?
      - Can the approval record which specific resources the user picked?
      instructions:
      - text: Approve OAuth2 grant {grant_id} in project {project_id}.
        slots:
          grant_id: requestBody.grant_id
          project_id: path.project_id
      - text: Approve grant {grant_id} for project {project_id} with scope {scope} and return the redirect URL.
        slots:
          grant_id: requestBody.grant_id
          project_id: path.project_id
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/authorize'].get
  update:
    x-apievangelist-phrasing:
      intent: Start OAuth2 authorization via a GET redirect
      effect: read
      questions:
      - What URL do I send a user's browser to so they can sign in to my app with Appwrite OAuth2?
      - Can I use PKCE with a code challenge in the authorize query string?
      instructions:
      - text: Build the GET authorize URL for project {project_id}, client {client_id}, redirecting to {redirect_uri}.
        slots:
          project_id: path.project_id
          client_id: query.client_id
          redirect_uri: query.redirect_uri
      - text: Start a query-string authorization in project {project_id} for client {client_id} with scope {scope} and PKCE challenge {code_challenge}.
        slots:
          project_id: path.project_id
          client_id: query.client_id
          scope: query.scope
          code_challenge: query.code_challenge
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/authorize'].post
  update:
    x-apievangelist-phrasing:
      intent: Start OAuth2 authorization via a form POST
      effect: read
      questions:
      - Can I send the authorization request as a POST body instead of URL parameters?
      - Which fields go in the form-post version of the authorize request?
      instructions:
      - text: POST an authorization request to project {project_id} for client {client_id} with redirect URI {redirect_uri} in the body.
        slots:
          project_id: path.project_id
          client_id: requestBody.client_id
          redirect_uri: requestBody.redirect_uri
      - text: Submit a form-post authorize for project {project_id} using pushed request handle {request_uri}.
        slots:
          project_id: path.project_id
          request_uri: requestBody.request_uri
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/device_authorization'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a device-code sign-in flow
      effect: write
      questions:
      - How do I let users sign in on a TV or CLI that has no browser?
      - What does the device authorization step return, like the user code and polling interval?
      instructions:
      - text: Start device authorization in project {project_id} for client {client_id}.
        slots:
          project_id: path.project_id
          client_id: requestBody.client_id
      - text: Get a device code and user code for client {client_id} in project {project_id} with scope {scope}.
        slots:
          client_id: requestBody.client_id
          project_id: path.project_id
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/grants'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange a device user code for a grant
      effect: write
      questions:
      - What happens after a user types the device code shown on their TV?
      - How is the signed-in user bound to a pending device grant?
      instructions:
      - text: Redeem device user code {user_code} in project {project_id}.
        slots:
          user_code: requestBody.user_code
          project_id: path.project_id
      - text: Bind my session to the pending device grant for code {user_code}, project {project_id}.
        slots:
          user_code: requestBody.user_code
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/grants/{grant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pending grant for the consent screen
      effect: read
      questions:
      - What details should my consent screen show about the access being requested?
      - Who is allowed to read an OAuth2 grant?
      instructions:
      - text: Show OAuth2 grant {grant_id} in project {project_id}.
        slots:
          grant_id: path.grant_id
          project_id: path.project_id
      - text: Fetch what grant {grant_id} in project {project_id} asks the user to approve.
        slots:
          grant_id: path.grant_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/logout'].get
  update:
    x-apievangelist-phrasing:
      intent: Log out via an OIDC GET redirect
      effect: destructive
      questions:
      - What URL do I redirect to for OpenID Connect logout from my app?
      - Will the logout link send the user back to my site afterward?
      instructions:
      - text: Build the GET logout link for project {project_id} with ID token hint {id_token_hint}.
        slots:
          project_id: path.project_id
          id_token_hint: query.id_token_hint
      - text: Sign the user out of project {project_id} by query string and return them to {post_logout_redirect_uri}.
        slots:
          project_id: path.project_id
          post_logout_redirect_uri: query.post_logout_redirect_uri
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/logout'].post
  update:
    x-apievangelist-phrasing:
      intent: Log out via an OIDC form POST
      effect: destructive
      questions:
      - Can I end the session with a POST body instead of logout URL parameters?
      - Which fields does the form-post logout accept?
      instructions:
      - text: POST a logout to project {project_id} with ID token hint {id_token_hint} in the body.
        slots:
          project_id: path.project_id
          id_token_hint: requestBody.id_token_hint
      - text: Submit a form-post logout for client {client_id} in project {project_id}, then return to {post_logout_redirect_uri}.
        slots:
          client_id: requestBody.client_id
          project_id: path.project_id
          post_logout_redirect_uri: requestBody.post_logout_redirect_uri
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations an access token can reach
      effect: read
      questions:
      - Which organizations does this OAuth2 access token give me access to?
      - How is an organization wildcard in the token expanded?
      instructions:
      - text: List the organizations my token can access in project {project_id}.
        slots:
          project_id: path.project_id
      - text: Search organizations accessible to the token in project {project_id} for {search}.
        slots:
          project_id: path.project_id
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/par'].post
  update:
    x-apievangelist-phrasing:
      intent: Push an authorization request server-side
      effect: write
      questions:
      - How do I use pushed authorization requests instead of long authorize URLs?
      - What request_uri handle do I pass to the authorize step?
      instructions:
      - text: Push an authorization request to project {project_id} for client {client_id}, redirect {redirect_uri}, response type {response_type}.
        slots:
          project_id: path.project_id
          client_id: requestBody.client_id
          redirect_uri: requestBody.redirect_uri
          response_type: requestBody.response_type
      - text: Create a PAR request_uri in project {project_id} for client {client_id} ({response_type}) returning to {redirect_uri} with scope {scope}.
        slots:
          project_id: path.project_id
          client_id: requestBody.client_id
          response_type: requestBody.response_type
          redirect_uri: requestBody.redirect_uri
          scope: requestBody.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/projects'].get
  update:
    x-apievangelist-phrasing:
      intent: List projects an access token can reach
      effect: read
      questions:
      - Which projects can my OAuth2 access token act on?
      - Can I search the projects a token has been granted?
      instructions:
      - text: List the projects my token can access via project {project_id}.
        slots:
          project_id: path.project_id
      - text: Search token-accessible projects in {project_id} for {search}.
        slots:
          project_id: path.project_id
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/reject'].post
  update:
    x-apievangelist-phrasing:
      intent: Deny a consent grant
      effect: write
      questions:
      - What happens when a user clicks deny on my consent screen?
      - Where is the user redirected after refusing access?
      instructions:
      - text: Reject OAuth2 grant {grant_id} in project {project_id}.
        slots:
          grant_id: requestBody.grant_id
          project_id: path.project_id
      - text: Deny consent for grant {grant_id} in project {project_id} and give me the access_denied redirect.
        slots:
          grant_id: requestBody.grant_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke an access or refresh token
      effect: destructive
      questions:
      - How do I invalidate an OAuth2 refresh token?
      - Can I hint whether the token I'm revoking is an access or refresh token?
      instructions:
      - text: Revoke token {token} in project {project_id}.
        slots:
          token: requestBody.token
          project_id: path.project_id
      - text: Revoke {token_type_hint} {token} for client {client_id} in project {project_id}.
        slots:
          token_type_hint: requestBody.token_type_hint
          token: requestBody.token
          client_id: requestBody.client_id
          project_id: path.project_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/oauth2/{project_id}/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 refresh tokens?
      - Can I get a new access token using my refresh token?
      - What grant type do I use to poll with a device code?
      instructions:
      - text: Exchange authorization code {code} for tokens in project {project_id} with grant type {grant_type}.
        slots:
          code: requestBody.code
          project_id: path.project_id
          grant_type: requestBody.grant_type
      - text: Refresh my access token in project {project_id} using {refresh_token} and grant type {grant_type}.
        slots:
          project_id: path.project_id
          refresh_token: requestBody.refresh_token
          grant_type: requestBody.grant_type
      method: generated
      generated: '2026-09-26'