API Evangelist conversational phrasing for Tray Ai Authentications API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Tray Ai Authentications API
  version: 1.0.0
extends: openapi/tray-ai-authentications-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: 16
- target: $.paths['/graphql#createUserAuthentication'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a third-party auth for an embedded user
      effect: write
      questions:
      - How do I store an end user's third-party credentials so a solution instance can use them?
      - Does the createUserAuthentication GraphQL mutation return an authId I can pass to solution instances?
      instructions:
      - text: Run the createUserAuthentication GraphQL mutation with variables {variables} for my end user.
        slots:
          variables: requestBody.variables
      - text: Send GraphQL mutation {mutation} to add a service authentication and give me back the authId.
        slots:
          mutation: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/graphql#getAuthentications'].post
  update:
    x-apievangelist-phrasing:
      intent: Query authentications through GraphQL
      effect: read
      questions:
      - With a master token, does the getAuthentications GraphQL query return every user's authentications?
      - Can a user token query only that user's own third-party authentications over GraphQL?
      instructions:
      - text: Run the getAuthentications GraphQL query {query} and list the results.
        slots:
          query: requestBody.query
      - text: Query GraphQL for authentications scoped to the current user token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/graphql#deleteAuthentication'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete an authentication with a GraphQL mutation
      effect: destructive
      questions:
      - Which token does the GraphQL delete-authentication mutation require?
      - Can I revoke an embedded user's stored service credentials through the GraphQL API?
      instructions:
      - text: Run the GraphQL delete-authentication mutation for auth {auth} with the user token.
        slots:
          auth: requestBody.variables
      - text: Send GraphQL mutation {mutation} to remove a user's third-party authentication.
        slots:
          mutation: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/      '].post
  update:
    x-apievangelist-phrasing:
      intent: Get user authentications from the embedded root endpoint
      effect: read
      questions:
      - What does the embedded API root return when I post a get-authentications query with a user or master token?
      - Can I fetch authentications by posting to the root of the Tray Embedded endpoint?
      instructions:
      - text: Post to the embedded root endpoint to get user authentications, filtered by {variables}.
        slots:
          variables: requestBody.variables
      - text: Fetch authentications from the embedded root endpoint using my master token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/       '].post
  update:
    x-apievangelist-phrasing:
      intent: Create user auth via the embedded root endpoint
      effect: write
      questions:
      - Can I create a user auth by posting to the embedded root endpoint with either a user or master token?
      - Which embedded root call adds new service credentials for an end user?
      instructions:
      - text: Post a create-user-auth call to the embedded root with variables {variables}.
        slots:
          variables: requestBody.variables
      - text: Add a user auth through the embedded root endpoint using my master token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/        '].post
  update:
    x-apievangelist-phrasing:
      intent: Delete user auth via the embedded root endpoint
      effect: destructive
      questions:
      - Is there an embedded root call that deletes a user auth with a user or master token?
      - Can a master token remove an end user's auth by posting to the embedded root endpoint?
      instructions:
      - text: Post a delete-user-auth call to the embedded root for auth {variables}.
        slots:
          variables: requestBody.variables
      - text: Remove a user auth through the embedded root endpoint with my master token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authentications'].get
  update:
    x-apievangelist-phrasing:
      intent: List authentications on the unversioned endpoint
      effect: read
      questions:
      - Which authentications belong to my user or organization on the plain /authentications endpoint?
      - Can I see every saved service authentication in my Tray organization?
      instructions:
      - text: List all authentications for my organization from the unversioned authentications endpoint.
      - text: Show the service authentications tied to my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authentications'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an authentication for Call Connector
      effect: write
      questions:
      - How do I create an authentication I can then use with the Call Connector endpoint?
      - What does the unversioned create-authentication call need besides a service environment id?
      instructions:
      - text: Create an authentication named {name} for service environment {environment} on the unversioned endpoint.
        slots:
          name: requestBody.name
          environment: requestBody.serviceEnvironmentId
      - text: Save credentials {credentials} as auth {name} for environment {environment} to use with Call Connector.
        slots:
          credentials: requestBody.credentials
          name: requestBody.name
          environment: requestBody.serviceEnvironmentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authentications/{authenticationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get authentication metadata by id
      effect: read
      questions:
      - What scopes and service environment does a given authentication have?
      - Can I look up an authentication's name and metadata on the unversioned endpoint?
      instructions:
      - text: Show the metadata for authentication {auth} from the unversioned authentications endpoint.
        slots:
          auth: path.authenticationId
      - text: Get the scopes and serviceEnvironmentId of auth {auth}.
        slots:
          auth: path.authenticationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/authentications/{authenticationId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an authentication by id (unversioned)
      effect: destructive
      questions:
      - Can I delete an authentication by id with a plain DELETE on /authentications?
      - What removes a stored credential from the unversioned authentications resource?
      instructions:
      - text: Delete authentication {auth} using the unversioned authentications endpoint.
        slots:
          auth: path.authenticationId
      - text: Remove stored credential {auth} from /authentications.
        slots:
          auth: path.authenticationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/authentications'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an authentication with core v1
      effect: write
      questions:
      - Can a core v1 authentication be tied to an on-prem agent group?
      - How do I create an authentication with specific scopes through the core v1 API?
      instructions:
      - text: Create core v1 authentication {name} for service environment {environment} with scopes {scopes}.
        slots:
          name: requestBody.name
          environment: requestBody.serviceEnvironmentId
          scopes: requestBody.scopes
      - text: Create core v1 auth {name} for environment {environment} routed through on-prem agent group {agent_group}.
        slots:
          name: requestBody.name
          environment: requestBody.serviceEnvironmentId
          agent_group: requestBody.onPremAgentGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/authentications/{authentication-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a core v1 authentication by id
      effect: read
      questions:
      - What does the core v1 API return for a single authentication id?
      - Which details of a core v1 authentication can I read without the credentials?
      instructions:
      - text: Get core v1 authentication {auth}.
        slots:
          auth: path.authentication-id
      - text: Show the core v1 record for authentication {auth} without its secrets.
        slots:
          auth: path.authentication-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/authentications/{authentication-id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an authentication's credentials
      effect: write
      questions:
      - How do I rotate the credentials on an existing authentication?
      - Can I rename an authentication or change its scopes after creating it?
      instructions:
      - text: Update authentication {auth} with new credentials {credentials} and name {name}.
        slots:
          auth: path.authentication-id
          credentials: requestBody.credentials
          name: requestBody.name
      - text: Change the scopes on authentication {auth} to {scopes}, keeping name {name} and credentials {credentials}.
        slots:
          auth: path.authentication-id
          scopes: requestBody.scopes
          name: requestBody.name
          credentials: requestBody.credentials
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/authentications/{authentication-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a core v1 authentication
      effect: destructive
      questions:
      - Can I delete an authentication through the core v1 API?
      - Which core v1 call permanently removes an authentication by id?
      instructions:
      - text: Delete core v1 authentication {auth}.
        slots:
          auth: path.authentication-id
      - text: Permanently remove auth {auth} via core v1.
        slots:
          auth: path.authentication-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/authentications/{authentication-id}/full'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an authentication including its credentials
      effect: read
      questions:
      - Can I retrieve the full authentication, including credentials, for a given id?
      - Is there a way to force an OAuth token refresh when reading an authentication?
      instructions:
      - text: Get the full authentication {auth} including its credentials.
        slots:
          auth: path.authentication-id
      - text: Fetch full auth {auth} and force a token refresh ({force_refresh}).
        slots:
          auth: path.authentication-id
          force_refresh: query.forceRefresh
      method: generated
      generated: '2026-09-26'
- target: $.paths['/core/v1/services/{service-name}/versions/{service-version}/environments'].get
  update:
    x-apievangelist-phrasing:
      intent: List a service's environments
      effect: read
      questions:
      - Where do I find the serviceEnvironmentId needed to create an authentication?
      - Which environments does a given service version offer?
      instructions:
      - text: List the environments for service {service} version {version}.
        slots:
          service: path.service-name
          version: path.service-version
      - text: Find the service environment ids for {service} at version {version}.
        slots:
          service: path.service-name
          version: path.service-version
      method: generated
      generated: '2026-09-26'