# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Canonical Identities API
  version: 1.0.0
extends: openapi/canonical-identities-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 28
- target: $.paths['/1.0/auth/identities'].get
  update:
    x-apievangelist-phrasing:
      intent: List URLs of all identities across auth methods
      effect: read
      questions:
      - Where can I get the URLs of every identity LXD knows about, whatever the auth method?
      - Is there a quick way to enumerate all identity links on my LXD server without full records?
      instructions:
      - text: Give me the URL of every identity on the LXD server.
      - text: Enumerate all identity links regardless of authentication method.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/bearer'].get
  update:
    x-apievangelist-phrasing:
      intent: List URLs of bearer identities
      effect: read
      questions:
      - Which bearer-token identities exist on my LXD server, as a list of links?
      - How do I get just the URLs of bearer identities in LXD?
      instructions:
      - text: List the URLs of all bearer identities.
      - text: Give me the links for every bearer-token identity on this server.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/bearer'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a bearer identity
      effect: write
      questions:
      - How do I add a new bearer-token identity to LXD?
      - Can I put a new bearer identity into authorization groups when I create it?
      instructions:
      - text: Create a bearer identity named {name} of type {type}.
        slots:
          name: requestBody.name
          type: requestBody.type
      - text: Add bearer identity {name} and place it in groups {groups}.
        slots:
          name: requestBody.name
          groups: requestBody.groups
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/bearer/{nameOrID}/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a new token for a bearer identity
      effect: destructive
      questions:
      - How do I generate a fresh token for an existing bearer identity?
      - Does issuing a new bearer token revoke the one the identity already had?
      - Can I set an expiry on a bearer identity's token?
      instructions:
      - text: Issue a new token for this bearer identity that expires after {expiry}.
        slots:
          expiry: requestBody.expiry
      - text: Rotate the token of bearer identity {identity}, replacing whatever token it had.
        slots:
          identity: path.nameOrID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/bearer/{nameOrID}/token'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a bearer identity's token
      effect: destructive
      questions:
      - How can I revoke the token of a bearer identity without deleting the identity itself?
      - Can I cut off a bearer identity's access by killing its current token?
      instructions:
      - text: Revoke the current token for this bearer identity but keep the identity.
      - text: Invalidate the bearer token held by identity {identity}.
        slots:
          identity: path.nameOrID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/bearer/{nameOrIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one bearer identity
      effect: read
      questions:
      - What groups is a particular bearer identity in?
      - Can I look up a single bearer identity by its name or ID?
      instructions:
      - text: Show me the details of bearer identity {identity}.
        slots:
          identity: path.nameOrIdentifier
      - text: Look up one bearer identity by name or identifier.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/bearer/{nameOrIdentifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a bearer identity's editable fields
      effect: write
      questions:
      - How do I overwrite all editable fields of a bearer identity at once?
      - Can I replace a bearer identity's group list entirely?
      instructions:
      - text: Replace the groups of bearer identity {identity} with exactly {groups}.
        slots:
          identity: path.nameOrIdentifier
          groups: requestBody.groups
      - text: Fully rewrite the bearer identity with groups {groups} and certificate {tls_certificate}.
        slots:
          groups: requestBody.groups
          tls_certificate: requestBody.tls_certificate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/bearer/{nameOrIdentifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a bearer identity
      effect: destructive
      questions:
      - How do I remove a bearer identity from LXD completely?
      - What happens when I delete a bearer-token identity?
      instructions:
      - text: Delete bearer identity {identity} from the server.
        slots:
          identity: path.nameOrIdentifier
      - text: Remove this bearer-token identity entirely.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/bearer/{nameOrIdentifier}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a bearer identity
      effect: write
      questions:
      - Can I change only some fields of a bearer identity and leave the rest alone?
      - Is there a way to tweak a bearer identity's groups without a full replace?
      instructions:
      - text: Patch bearer identity {identity} so its groups become {groups}, leaving other fields untouched.
        slots:
          identity: path.nameOrIdentifier
          groups: requestBody.groups
      - text: Partially update the bearer identity's certificate to {tls_certificate}.
        slots:
          tls_certificate: requestBody.tls_certificate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/bearer?recursion=1'].get
  update:
    x-apievangelist-phrasing:
      intent: List bearer identities with full details
      effect: read
      questions:
      - Can I see the full records of all bearer identities, including their groups?
      - What does each bearer-token identity on the server look like in detail?
      instructions:
      - text: Fetch full details for every bearer identity, not just links.
      - text: Show all bearer-token identities with their groups and settings.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/current'].get
  update:
    x-apievangelist-phrasing:
      intent: Show the identity making the request
      effect: read
      questions:
      - Who am I authenticated as against this LXD server?
      - What permissions does my own current identity have?
      instructions:
      - text: Tell me which identity I'm using and what it's authorized to do.
      - text: Show my current identity with its authorization context.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/oidc'].get
  update:
    x-apievangelist-phrasing:
      intent: List URLs of OIDC identities
      effect: read
      questions:
      - Which users have signed in to LXD via OIDC, as a list of links?
      - How do I get just the URLs of OIDC identities?
      instructions:
      - text: List the URLs of all OIDC identities.
      - text: Give me links to every single sign-on identity on this server.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/oidc/{nameOrIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one OIDC identity
      effect: read
      questions:
      - What groups does a specific OIDC user belong to in LXD?
      - Can I look up a single OIDC identity by name or ID?
      instructions:
      - text: Show me the OIDC identity {identity}.
        slots:
          identity: path.nameOrIdentifier
      - text: Look up one single sign-on identity by its name or identifier.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/oidc/{nameOrIdentifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an OIDC identity's editable fields
      effect: write
      questions:
      - How do I overwrite all editable fields on an OIDC identity?
      - Can I set an OIDC user's groups to an exact new list?
      instructions:
      - text: Replace the groups of OIDC identity {identity} with exactly {groups}.
        slots:
          identity: path.nameOrIdentifier
          groups: requestBody.groups
      - text: Fully rewrite the OIDC identity with groups {groups} and certificate {tls_certificate}.
        slots:
          groups: requestBody.groups
          tls_certificate: requestBody.tls_certificate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/oidc/{nameOrIdentifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an OIDC identity
      effect: destructive
      questions:
      - How do I remove an OIDC user's identity from LXD?
      - Can I delete a single sign-on identity that should no longer have access?
      instructions:
      - text: Delete the OIDC identity {identity}.
        slots:
          identity: path.nameOrIdentifier
      - text: Remove this single sign-on identity from the server.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/oidc/{nameOrIdentifier}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update an OIDC identity
      effect: write
      questions:
      - Can I change only an OIDC user's groups without replacing the whole identity?
      - Is a partial update possible for an OIDC identity?
      instructions:
      - text: Patch OIDC identity {identity} so its groups become {groups}, keeping everything else.
        slots:
          identity: path.nameOrIdentifier
          groups: requestBody.groups
      - text: Partially update the OIDC identity's certificate to {tls_certificate}.
        slots:
          tls_certificate: requestBody.tls_certificate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/oidc?recursion=1'].get
  update:
    x-apievangelist-phrasing:
      intent: List OIDC identities with full details
      effect: read
      questions:
      - Can I see full records of every OIDC identity, including groups?
      - What details does LXD hold for each OIDC-authenticated user?
      instructions:
      - text: Fetch full details for every OIDC identity, not just links.
      - text: Show all single sign-on identities with their groups.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/tls'].get
  update:
    x-apievangelist-phrasing:
      intent: List URLs of TLS identities
      effect: read
      questions:
      - Which TLS client certificates are registered as identities, as a list of links?
      - How do I get just the URLs of TLS identities in LXD?
      instructions:
      - text: List the URLs of all TLS identities.
      - text: Give me links to every certificate-based identity on this server.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/tls'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a trusted or pending TLS identity
      effect: write
      questions:
      - How do I trust a new client certificate in LXD?
      - Can I create a pending TLS identity and get a join token for an untrusted client?
      - Do I need to supply a certificate or a token when adding a TLS identity?
      instructions:
      - text: Trust client certificate {certificate} as TLS identity {name}.
        slots:
          certificate: requestBody.certificate
          name: requestBody.name
      - text: Create a pending TLS identity {name} in groups {groups} and return a token for it.
        slots:
          name: requestBody.name
          groups: requestBody.groups
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/tls/{nameOrIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one TLS identity
      effect: read
      questions:
      - What groups is a specific TLS certificate identity in?
      - Can I look up one certificate-based identity by name or ID?
      instructions:
      - text: Show me the TLS identity {identity}.
        slots:
          identity: path.nameOrIdentifier
      - text: Look up one certificate-based identity by name or identifier.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/tls/{nameOrIdentifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a TLS identity's editable fields
      effect: write
      questions:
      - How do I swap the certificate on an existing TLS identity?
      - Can I overwrite a TLS identity's groups and certificate in one go?
      instructions:
      - text: Replace the certificate of TLS identity {identity} with {tls_certificate}.
        slots:
          identity: path.nameOrIdentifier
          tls_certificate: requestBody.tls_certificate
      - text: Fully rewrite the TLS identity so its groups are exactly {groups}.
        slots:
          groups: requestBody.groups
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/tls/{nameOrIdentifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a TLS identity and revoke its trust
      effect: destructive
      questions:
      - How do I stop trusting a client certificate in LXD?
      - Does deleting a TLS identity also revoke its trust?
      instructions:
      - text: Delete TLS identity {identity} and revoke its trust.
        slots:
          identity: path.nameOrIdentifier
      - text: Untrust and remove this certificate-based client.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/tls/{nameOrIdentifier}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a TLS identity
      effect: write
      questions:
      - Can I change just the groups on a TLS client identity?
      - Is there a partial update for certificate-based identities?
      instructions:
      - text: Patch the groups of TLS identity {identity} to {groups}, leaving its certificate alone.
        slots:
          identity: path.nameOrIdentifier
          groups: requestBody.groups
      - text: Partially update only the certificate on this TLS identity to {tls_certificate}.
        slots:
          tls_certificate: requestBody.tls_certificate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/1.0/auth/identities/tls?public'].post
  update:
    x-apievangelist-phrasing:
      intent: Self-register a TLS client using a trust token
      effect: write
      questions:
      - As an untrusted client, how do I add my own certificate using a trust token?
      - Which certificate gets trusted when a client redeems a trust token over the public endpoint?
      instructions:
      - text: Redeem my trust token so the certificate from this TLS handshake becomes trusted.
      - text: Register this untrusted client's own certificate via the public trust-token endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities/tls?recursion=1'].get
  update:
    x-apievangelist-phrasing:
      intent: List TLS identities with full details
      effect: read
      questions:
      - Can I see full records of every TLS certificate identity at once?
      - What groups is each certificate-based client in?
      instructions:
      - text: Fetch full details for every TLS identity, not just links.
      - text: Show all certificate-based identities with their groups.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/1.0/auth/identities?recursion=1'].get
  update:
    x-apievangelist-phrasing:
      intent: List all identities with full details
      effect: read
      questions:
      - Can I pull the complete records of every identity in one call, bearer, OIDC and TLS together?
      - What groups and auth method does each identity on my LXD server have?
      instructions:
      - text: Fetch the full details of every identity on the server, not just URLs.
      - text: Show each identity's name, auth method and groups across all methods.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/identities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the map of all v1 identities
      effect: read
      questions:
      - Which identities are configured in the system through the v1 identities endpoint?
      - Can I see every v1 identity and its access level as one map keyed by name?
      instructions:
      - text: Show me the map of all identities from the v1 identities endpoint.
      - text: Dump every v1 identity name with its access settings.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/identities'].post
  update:
    x-apievangelist-phrasing:
      intent: Add, update, replace or remove v1 identities
      effect: write
      questions:
      - How can I add or remove several v1 identities in one request?
      - What actions does the v1 identities endpoint accept for changing identities?
      - Can I remove a v1 identity by setting its value to null?
      instructions:
      - text: Run v1 identities action {action} with identities {identities}.
        slots:
          action: requestBody.action
          identities: requestBody.identities
      - text: 'Add these v1 identities to the system: {identities}.'
        slots:
          identities: requestBody.identities
      - text: Remove the v1 identities listed in {identities} by nulling their values.
        slots:
          identities: requestBody.identities
      method: generated
      generated: '2026-10-01'