# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Flagsmith Authentication API
  version: 1.0.0
extends: openapi/flagsmith-authentication-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: 59
- target: $.paths['/api/v1/auth/{method}/activate/'].post
  update:
    x-apievangelist-phrasing:
      intent: Start enabling a two-factor method
      effect: write
      questions:
      - How do I begin turning on two-factor authentication for my account?
      - Can I start setting up an authenticator app as an MFA method?
      instructions:
      - text: Begin activating MFA method {method} on my account.
        slots:
          method: path.method
      - text: Start two-factor setup using the {method} method.
        slots:
          method: path.method
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/{method}/activate/confirm/'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm a two-factor method setup
      effect: write
      questions:
      - What is the final step to finish enabling two-factor authentication?
      - Once I've scanned the MFA code, how do I confirm it's working?
      instructions:
      - text: Confirm activation of MFA method {method}.
        slots:
          method: path.method
      - text: Finish two-factor setup for {method} with my verification code.
        slots:
          method: path.method
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/{method}/deactivate/'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn off a two-factor method
      effect: destructive
      questions:
      - Can I disable two-factor authentication on my account?
      - What removes an MFA method I no longer use?
      instructions:
      - text: Deactivate MFA method {method} on my account.
        slots:
          method: path.method
      - text: Turn off two-factor via {method}.
        slots:
          method: path.method
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/login/'].post
  update:
    x-apievangelist-phrasing:
      intent: Log in with email and password
      effect: write
      questions:
      - How do I get an auth token by logging in with my email and password?
      - Is password login rate limited if I try too many times?
      instructions:
      - text: Log me in as {email} with password {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      - text: Sign in to Flagsmith with email {email} and password {password} to get a token.
        slots:
          email: requestBody.email
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/login/code/'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete login with a two-factor code
      effect: write
      questions:
      - After my password, where do I submit the second-factor login code?
      - Can I finish a login that requires an MFA code?
      instructions:
      - text: Complete the two-factor login for {email} with the code step.
        slots:
          email: requestBody.email
      - text: Submit the MFA login code step for {email} using password {password}.
        slots:
          email: requestBody.email
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/logout/'].post
  update:
    x-apievangelist-phrasing:
      intent: Log out and remove my auth token
      effect: destructive
      questions:
      - How do I log out so my auth token stops working?
      - Does logging out invalidate the current session token?
      instructions:
      - text: Log me out of Flagsmith.
      - text: End my session by removing my authentication token through logout.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/mfa/user-active-methods/'].get
  update:
    x-apievangelist-phrasing:
      intent: List my active two-factor methods
      effect: read
      questions:
      - Which two-factor methods are currently switched on for my account?
      - Do I have MFA enabled right now?
      instructions:
      - text: Show my active MFA methods.
      - text: Check which two-factor methods are enabled on my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/oauth/github/'].post
  update:
    x-apievangelist-phrasing:
      intent: Sign in with GitHub
      effect: write
      questions:
      - Can I log in or sign up using my GitHub account?
      - What do I pass to exchange a GitHub access token for a Flagsmith session?
      instructions:
      - text: Sign me in with GitHub using access token {access_token}.
        slots:
          access_token: requestBody.access_token
      - text: Sign up through GitHub with token {access_token} and sign-up type {sign_up_type}.
        slots:
          access_token: requestBody.access_token
          sign_up_type: requestBody.sign_up_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/oauth/google/'].post
  update:
    x-apievangelist-phrasing:
      intent: Sign in with Google
      effect: write
      questions:
      - Can I log in or sign up using my Google account?
      - What do I pass to exchange a Google access token for a session?
      instructions:
      - text: Sign me in with Google using access token {access_token}.
        slots:
          access_token: requestBody.access_token
      - text: Sign up through Google with token {access_token}, marketing consent {marketing_consent_given}.
        slots:
          access_token: requestBody.access_token
          marketing_consent_given: requestBody.marketing_consent_given
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/oidc/token/'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange an OIDC token for an access token
      effect: write
      questions:
      - Can my CI pipeline swap its OIDC token for a short-lived access token?
      - How does workload identity federation from a trusted identity provider work here?
      instructions:
      - text: Exchange OIDC token {token} for a short-lived Flagsmith access token.
        slots:
          token: requestBody.token
      - text: Trade this identity provider token {token} for temporary API credentials.
        slots:
          token: requestBody.token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/{name}/request/'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a SAML login request
      effect: write
      questions:
      - How do I kick off a SAML single sign-on login for my organisation's configuration?
      - Where does SP-initiated SAML login begin?
      instructions:
      - text: Start a SAML login request for configuration {name}.
        slots:
          name: path.name
      - text: Generate the SAML authentication request for SSO config {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/{name}/response/'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle a SAML response from the identity provider
      effect: write
      questions:
      - Where should my identity provider post its SAML assertion?
      - What is the SAML assertion consumer endpoint for my configuration?
      instructions:
      - text: Process the SAML response for configuration {name}.
        slots:
          name: path.name
      - text: Consume the identity provider's SAML assertion for SSO config {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/attribute-mapping/'].get
  update:
    x-apievangelist-phrasing:
      intent: List SAML attribute mappings
      effect: read
      questions:
      - Which identity provider attributes are mapped to user fields for SAML?
      - Can I filter SAML attribute mappings to one SAML configuration?
      instructions:
      - text: List SAML attribute mappings for organisation {organisation}.
        slots:
          organisation: query.organisation
      - text: Show attribute mappings for SAML configuration {saml_configuration}.
        slots:
          saml_configuration: query.saml_configuration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/attribute-mapping/'].post
  update:
    x-apievangelist-phrasing:
      intent: Map an identity provider attribute to a user field
      effect: write
      questions:
      - How do I map an IdP attribute such as email to a user field for SAML?
      - Can I add a new attribute mapping to my SAML setup?
      instructions:
      - text: Map IdP attribute {idp_attribute_name} to user field {django_attribute_name} in SAML configuration {saml_configuration}.
        slots:
          idp_attribute_name: requestBody.idp_attribute_name
          django_attribute_name: requestBody.django_attribute_name
          saml_configuration: requestBody.saml_configuration
      - text: Add a SAML mapping from {idp_attribute_name} to {django_attribute_name} for config {saml_configuration}.
        slots:
          idp_attribute_name: requestBody.idp_attribute_name
          django_attribute_name: requestBody.django_attribute_name
          saml_configuration: requestBody.saml_configuration
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/attribute-mapping/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a SAML attribute mapping
      effect: read
      questions:
      - What does a specific SAML attribute mapping point to?
      - Which user field is one SAML mapping filling in?
      instructions:
      - text: Get SAML attribute mapping {id}.
        slots:
          id: path.id
      - text: Show which IdP attribute mapping {id} reads from.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/attribute-mapping/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a SAML attribute mapping
      effect: write
      questions:
      - How do I fully redefine an existing SAML attribute mapping?
      - Can I replace both sides of a SAML mapping at once?
      instructions:
      - text: Replace SAML mapping {id} so {idp_attribute_name} maps to {django_attribute_name} in config {saml_configuration}.
        slots:
          id: path.id
          idp_attribute_name: requestBody.idp_attribute_name
          django_attribute_name: requestBody.django_attribute_name
          saml_configuration: requestBody.saml_configuration
      - text: 'Overwrite attribute mapping {id} entirely for SAML configuration {saml_configuration}: {idp_attribute_name} to {django_attribute_name}.'
        slots:
          id: path.id
          saml_configuration: requestBody.saml_configuration
          idp_attribute_name: requestBody.idp_attribute_name
          django_attribute_name: requestBody.django_attribute_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/attribute-mapping/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a SAML attribute mapping
      effect: destructive
      questions:
      - How do I remove a SAML attribute mapping I no longer need?
      - Can I stop an IdP attribute from being mapped to a user field?
      instructions:
      - text: Delete SAML attribute mapping {id}.
        slots:
          id: path.id
      - text: Remove attribute mapping {id} from the SAML setup.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/attribute-mapping/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change the IdP attribute on a SAML mapping
      effect: write
      questions:
      - Can I change only the identity provider attribute name on a SAML mapping?
      - What if my IdP renamed an attribute that a mapping uses?
      instructions:
      - text: Point SAML mapping {id} at IdP attribute {idp_attribute_name}.
        slots:
          id: path.id
          idp_attribute_name: requestBody.idp_attribute_name
      - text: Change the user field on attribute mapping {id} to {django_attribute_name}.
        slots:
          id: path.id
          django_attribute_name: requestBody.django_attribute_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/configuration/'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organisation's SAML configurations
      effect: read
      questions:
      - Which SAML single sign-on configurations does my organisation have?
      - Is SAML SSO set up for a given organisation?
      instructions:
      - text: List SAML configurations for organisation {organisation}.
        slots:
          organisation: query.organisation
      - text: Show the SSO setups configured in organisation {organisation}.
        slots:
          organisation: query.organisation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/configuration/'].post
  update:
    x-apievangelist-phrasing:
      intent: Set up SAML single sign-on
      effect: write
      questions:
      - How do I configure SAML SSO for my organisation?
      - Can I upload my identity provider's metadata XML when setting up SAML?
      - Is IdP-initiated login supported for SAML?
      instructions:
      - text: Create SAML configuration {name} for organisation {organisation} with frontend URL {frontend_url}.
        slots:
          name: requestBody.name
          organisation: requestBody.organisation
          frontend_url: requestBody.frontend_url
      - text: Set up SSO {name} for organisation {organisation} at {frontend_url} using IdP metadata {idp_metadata_xml}.
        slots:
          name: requestBody.name
          organisation: requestBody.organisation
          frontend_url: requestBody.frontend_url
          idp_metadata_xml: requestBody.idp_metadata_xml
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/configuration/{name}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a SAML configuration
      effect: read
      questions:
      - What settings does a particular SAML configuration have?
      - Does my SAML setup allow IdP-initiated login?
      instructions:
      - text: Get SAML configuration {name}.
        slots:
          name: path.name
      - text: Show the frontend URL and IdP settings for SSO config {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/configuration/{name}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a SAML configuration
      effect: write
      questions:
      - How do I fully replace an existing SAML SSO configuration?
      - Can I redo every setting on my SAML configuration at once?
      instructions:
      - text: Replace SAML configuration {name} for organisation {organisation} with frontend URL {frontend_url}.
        slots:
          name: path.name
          organisation: requestBody.organisation
          frontend_url: requestBody.frontend_url
      - text: Overwrite SSO config {name} in organisation {organisation}, frontend {frontend_url}, IdP metadata {idp_metadata_xml}.
        slots:
          name: path.name
          organisation: requestBody.organisation
          frontend_url: requestBody.frontend_url
          idp_metadata_xml: requestBody.idp_metadata_xml
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/configuration/{name}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a SAML configuration
      effect: destructive
      questions:
      - How do I turn off SAML SSO by deleting its configuration?
      - Can I remove an old SAML configuration?
      instructions:
      - text: Delete SAML configuration {name}.
        slots:
          name: path.name
      - text: Remove SSO config {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/configuration/{name}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update IdP metadata or settings on SAML config
      effect: write
      questions:
      - Can I upload new identity provider metadata to an existing SAML setup?
      - How do I switch IdP-initiated login on for my SAML configuration?
      instructions:
      - text: Update SAML configuration {name} with new IdP metadata {idp_metadata_xml}.
        slots:
          name: path.name
          idp_metadata_xml: requestBody.idp_metadata_xml
      - text: Set allow IdP-initiated login to {allow_idp_initiated} on SSO config {name}.
        slots:
          allow_idp_initiated: requestBody.allow_idp_initiated
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/saml/login/'].post
  update:
    x-apievangelist-phrasing:
      intent: Log in with a SAML access token
      effect: write
      questions:
      - After SAML SSO, how do I turn the returned token into a session?
      - What completes a SAML login on the frontend?
      instructions:
      - text: Complete SAML login with access token {access_token}.
        slots:
          access_token: requestBody.access_token
      - text: Exchange SAML token {access_token} for a Flagsmith session.
        slots:
          access_token: requestBody.access_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/token/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke my authentication token
      effect: destructive
      questions:
      - Can I delete my current API auth token directly?
      - What revokes the token I'm authenticated with?
      instructions:
      - text: Revoke my current auth token.
      - text: Delete the authentication token I'm using right now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/'].get
  update:
    x-apievangelist-phrasing:
      intent: List user accounts
      effect: read
      questions:
      - Which user accounts can I see through the auth users endpoint?
      - Can I page through registered users?
      instructions:
      - text: List user accounts.
      - text: Show page {page} of registered users.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new user account
      effect: write
      questions:
      - How do I sign up a new user with email and password?
      - Can I record marketing consent when registering someone?
      instructions:
      - text: Register user {first_name} {last_name} with email {email} and password {password}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          email: requestBody.email
          password: requestBody.password
      - text: Sign up {email} as {first_name} {last_name}, password {password}, marketing consent {marketing_consent_given}.
        slots:
          email: requestBody.email
          first_name: requestBody.first_name
          last_name: requestBody.last_name
          password: requestBody.password
          marketing_consent_given: requestBody.marketing_consent_given
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user account by ID
      effect: read
      questions:
      - What are the details of a specific user account?
      - Can I look up another user by their ID?
      instructions:
      - text: Get user account {id}.
        slots:
          id: path.id
      - text: Show the name and email of user {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a user's name details
      effect: write
      questions:
      - How do I fully update another user's first and last name?
      - Can I replace a user account's profile by ID?
      instructions:
      - text: Set user {id}'s name to {first_name} {last_name}.
        slots:
          id: path.id
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      - text: Replace the profile of user {id} with first name {first_name} and last name {last_name}.
        slots:
          id: path.id
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user account
      effect: destructive
      questions:
      - How do I delete a user account by its ID?
      - Can I also delete organisations that would be left with no users?
      instructions:
      - text: Delete user account {id}, confirming with password {current_password}.
        slots:
          id: path.id
          current_password: query.current_password
      - text: Delete user {id} and orphaned organisations {delete_orphan_organisations}.
        slots:
          id: path.id
          delete_orphan_organisations: query.delete_orphan_organisations
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change one detail on a user account
      effect: write
      questions:
      - Can I change just the last name on another user's account?
      - What lets me patch a single field on a user by ID?
      instructions:
      - text: Change user {id}'s last name to {last_name}.
        slots:
          id: path.id
          last_name: requestBody.last_name
      - text: Update only the first name of user {id} to {first_name}.
        slots:
          id: path.id
          first_name: requestBody.first_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/activation/'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a new account from its email link
      effect: write
      questions:
      - What activates an account using the uid and token from the activation email?
      - My activation link has a uid and token — where do those go?
      instructions:
      - text: Activate the account with uid {uid} and token {token}.
        slots:
          uid: requestBody.uid
          token: requestBody.token
      - text: Confirm sign-up using activation uid {uid} and token {token}.
        slots:
          uid: requestBody.uid
          token: requestBody.token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/me/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my own user profile
      effect: read
      questions:
      - Who am I logged in as?
      - What does my own account profile look like, including when I joined?
      instructions:
      - text: Show my own user profile.
      - text: Tell me which account I'm authenticated as.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/me/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace my own profile details
      effect: write
      questions:
      - How do I update my own first and last name in one full replacement?
      - Can I reset my whole profile at once?
      instructions:
      - text: Replace my profile with first name {first_name} and last name {last_name}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      - text: Rewrite my own account as {first_name} {last_name}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/me/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete my own account
      effect: destructive
      questions:
      - How do I close and delete my own account?
      - Can I remove myself completely?
      instructions:
      - text: Delete my own account.
      - text: Close the account I'm logged in with permanently.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/me/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit one field of my own profile
      effect: write
      questions:
      - Can I change just my first name?
      - What updates my own email signature for support messages?
      instructions:
      - text: Change my first name to {first_name}.
        slots:
          first_name: requestBody.first_name
      - text: Set my support email signature to {pylon_email_signature}.
        slots:
          pylon_email_signature: requestBody.pylon_email_signature
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/me/onboarding/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update my onboarding details
      effect: write
      questions:
      - Where do I save my details during the onboarding flow?
      - Can onboarding record how I signed up?
      instructions:
      - text: Save my onboarding details with sign-up type {sign_up_type}.
        slots:
          sign_up_type: requestBody.sign_up_type
      - text: Update my onboarding profile as {first_name} {last_name}.
        slots:
          first_name: requestBody.first_name
          last_name: requestBody.last_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/resend_activation/'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend the account activation email
      effect: write
      questions:
      - I never got my activation email — can it be sent again?
      - What resends the sign-up confirmation link?
      instructions:
      - text: Resend the activation email to {email}.
        slots:
          email: requestBody.email
      - text: Send {email} a fresh account activation link.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/reset_email/'].post
  update:
    x-apievangelist-phrasing:
      intent: Request an email address reset
      effect: write
      questions:
      - How do I start the process of resetting the email on an account?
      - Can I request an email-change link for an account?
      instructions:
      - text: Request an email reset for account {email}.
        slots:
          email: requestBody.email
      - text: Send an email-change link to {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/reset_email_confirm/'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm a new email address after reset
      effect: write
      questions:
      - What finishes an email reset by setting the new address?
      - Once I have the reset link, where do I submit my new email?
      instructions:
      - text: Confirm the email reset with new address {new_email}.
        slots:
          new_email: requestBody.new_email
      - text: Complete the email change to {new_email}.
        slots:
          new_email: requestBody.new_email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/reset_password/'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a password reset email
      effect: write
      questions:
      - I forgot my password — how do I get a reset email?
      - Can I trigger a password reset link for an account?
      instructions:
      - text: Send a password reset email to {email}.
        slots:
          email: requestBody.email
      - text: Start a forgotten-password reset for {email}.
        slots:
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/reset_password_confirm/'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a new password from a reset link
      effect: write
      questions:
      - What sets my new password using the uid and token from the reset email?
      - Do I have to enter the new password twice when resetting it?
      instructions:
      - text: Reset the password with uid {uid} and token {token} to {new_password}, confirmed as {re_new_password}.
        slots:
          uid: requestBody.uid
          token: requestBody.token
          new_password: requestBody.new_password
          re_new_password: requestBody.re_new_password
      - text: Finish the password reset for uid {uid}, token {token}, new password {new_password} repeated {re_new_password}.
        slots:
          uid: requestBody.uid
          token: requestBody.token
          new_password: requestBody.new_password
          re_new_password: requestBody.re_new_password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/set_email/'].post
  update:
    x-apievangelist-phrasing:
      intent: Change my email while logged in
      effect: write
      questions:
      - How do I change my login email if I know my current password?
      - Does changing my email require my current password?
      instructions:
      - text: Change my email to {new_email} using my current password {current_password}.
        slots:
          new_email: requestBody.new_email
          current_password: requestBody.current_password
      - text: Set my account email to {new_email}, verifying with {current_password}.
        slots:
          new_email: requestBody.new_email
          current_password: requestBody.current_password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/auth/users/set_password/'].post
  update:
    x-apievangelist-phrasing:
      intent: Change my password while logged in
      effect: write
      questions:
      - Can I change my password when I still know the old one?
      - What changes my password without going through a reset email?
      instructions:
      - text: Change my password from {current_password} to {new_password}, confirmed {re_new_password}.
        slots:
          current_password: requestBody.current_password
          new_password: requestBody.new_password
          re_new_password: requestBody.re_new_password
      - text: Update my password to {new_password} (repeat {re_new_password}) using current password {current_password}.
        slots:
          new_password: requestBody.new_password
          re_new_password: requestBody.re_new_password
          current_password: requestBody.current_password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/groups/{group_pk}/users/{user_pk}/make-admin'].post
  update:
    x-apievangelist-phrasing:
      intent: Make a user a group admin
      effect: write
      questions:
      - How do I give someone admin rights over a user group?
      - Can a group member be promoted to group admin?
      instructions:
      - text: Make user {user_pk} an admin of group {group_pk} in organisation {organisation_pk}.
        slots:
          user_pk: path.user_pk
          group_pk: path.group_pk
          organisation_pk: path.organisation_pk
      - text: Promote {user_pk} to group admin on group {group_pk} in {organisation_pk}.
        slots:
          user_pk: path.user_pk
          group_pk: path.group_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/groups/{group_pk}/users/{user_pk}/remove-admin'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a user's group admin rights
      effect: write
      questions:
      - Can I demote a group admin back to a regular member?
      - What takes away someone's admin role on a user group?
      instructions:
      - text: Remove admin rights from user {user_pk} on group {group_pk} in organisation {organisation_pk}.
        slots:
          user_pk: path.user_pk
          group_pk: path.group_pk
          organisation_pk: path.organisation_pk
      - text: Demote {user_pk} from group admin of {group_pk} in {organisation_pk}.
        slots:
          user_pk: path.user_pk
          group_pk: path.group_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/roles/{role_pk}/users/'].get
  update:
    x-apievangelist-phrasing:
      intent: List users assigned to a role
      effect: read
      questions:
      - Which users hold a particular role in my organisation?
      - Who has been given this role?
      instructions:
      - text: List users assigned to role {role_pk} in organisation {organisation_pk}.
        slots:
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      - text: Show everyone holding role {role_pk} in {organisation_pk}.
        slots:
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/roles/{role_pk}/users/'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign a role to a user
      effect: write
      questions:
      - How do I give a user a role in my organisation?
      - Can I add someone to an existing role?
      instructions:
      - text: Assign user {user} to role {role_pk} in organisation {organisation_pk}.
        slots:
          user: requestBody.user
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      - text: Give {user} the role {role_pk} in {organisation_pk}.
        slots:
          user: requestBody.user
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/roles/{role_pk}/users/{id}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's role assignment
      effect: read
      questions:
      - What does a single user-role assignment record contain?
      - Is a given role assignment still in place?
      instructions:
      - text: Get role assignment {id} for role {role_pk} in organisation {organisation_pk}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      - text: Show user-role record {id} under role {role_pk} in {organisation_pk}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/roles/{role_pk}/users/{id}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a user-role assignment
      effect: write
      questions:
      - Can I swap which user a role assignment points to?
      - How do I fully redo one user-role assignment?
      instructions:
      - text: Replace role assignment {id} on role {role_pk} in {organisation_pk} with user {user}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
          user: requestBody.user
      - text: Overwrite user-role record {id} for role {role_pk} in organisation {organisation_pk} to point at {user}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/roles/{role_pk}/users/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a role
      effect: destructive
      questions:
      - How do I take a role away from a user, working from the role's member list?
      - Can I unassign someone from a role by the assignment ID?
      instructions:
      - text: Remove role assignment {id} from role {role_pk} in organisation {organisation_pk}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      - text: Unassign member {id} from role {role_pk} in {organisation_pk}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/roles/{role_pk}/users/{id}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a user-role assignment
      effect: write
      questions:
      - Can I move a user-role assignment to a different role?
      - What changes just one field of a role assignment?
      instructions:
      - text: Move assignment {id} under role {role_pk} in {organisation_pk} to role {role}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
          role: requestBody.role
      - text: Patch role assignment {id} on role {role_pk} in organisation {organisation_pk} to user {user}.
        slots:
          id: path.id
          role_pk: path.role_pk
          organisation_pk: path.organisation_pk
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/users/'].get
  update:
    x-apievangelist-phrasing:
      intent: List members of an organisation
      effect: read
      questions:
      - Who are the members of my organisation?
      - Can I see every user in an organisation?
      instructions:
      - text: List users in organisation {organisation_pk}.
        slots:
          organisation_pk: path.organisation_pk
      - text: Show all members of organisation {organisation_pk}.
        slots:
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/users/{id}/update-role/'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a member's organisation role
      effect: write
      questions:
      - How do I make an organisation member an admin or a regular user?
      - Can I change someone's role in the organisation?
      instructions:
      - text: Set user {id}'s organisation role to {role} in organisation {organisation_pk}.
        slots:
          id: path.id
          role: requestBody.role
          organisation_pk: path.organisation_pk
      - text: Change member {id} in {organisation_pk} to organisation role {role}.
        slots:
          id: path.id
          organisation_pk: path.organisation_pk
          role: requestBody.role
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/users/{user_pk}/roles/'].get
  update:
    x-apievangelist-phrasing:
      intent: List the roles a user holds
      effect: read
      questions:
      - Which roles has a particular user been given in my organisation?
      - What roles does this teammate hold?
      instructions:
      - text: List the roles held by user {user_pk} in organisation {organisation_pk}.
        slots:
          user_pk: path.user_pk
          organisation_pk: path.organisation_pk
      - text: Show every role assigned to {user_pk} in {organisation_pk}.
        slots:
          user_pk: path.user_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/organisations/{organisation_pk}/users/{user_pk}/roles/{id}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a role from a user
      effect: destructive
      questions:
      - Can I remove one role from a user, working from that user's list of roles?
      - What strips a specific role off a teammate?
      instructions:
      - text: Remove role {id} from user {user_pk} in organisation {organisation_pk}.
        slots:
          id: path.id
          user_pk: path.user_pk
          organisation_pk: path.organisation_pk
      - text: Take role {id} away from {user_pk} in {organisation_pk}.
        slots:
          id: path.id
          user_pk: path.user_pk
          organisation_pk: path.organisation_pk
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/join/{hash}/'].post
  update:
    x-apievangelist-phrasing:
      intent: Join an organisation from an email invite
      effect: write
      questions:
      - I got an invite email to an organisation — how do I accept it?
      - What accepts a personal organisation invitation?
      instructions:
      - text: Accept the organisation email invite {hash}.
        slots:
          hash: path.hash
      - text: Join the organisation using invitation hash {hash}.
        slots:
          hash: path.hash
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/users/join/link/{hash}/'].post
  update:
    x-apievangelist-phrasing:
      intent: Join an organisation from a shared invite link
      effect: write
      questions:
      - Can I join an organisation using a shared invite link rather than an emailed invite?
      - What accepts a reusable organisation invite link?
      instructions:
      - text: Join the organisation through shared invite link {hash}.
        slots:
          hash: path.hash
      - text: Use invite link hash {hash} to join its organisation.
        slots:
          hash: path.hash
      method: generated
      generated: '2026-09-26'