Canonical · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Identity Platform Idps Service API

6 actions 6 updates phrasing extends openapi/canonical-idpsservice-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Canonical's API. It is a proposal applied on top of the contract, not a document Canonical publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 6

$.info

$.paths['/api/v0/idps'].get

$.paths['/api/v0/idps'].post

$.paths['/api/v0/idps/{id}'].get

$.paths['/api/v0/idps/{id}'].delete

$.paths['/api/v0/idps/{id}'].patch

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity Platform Idps Service API
  version: 1.0.0
extends: openapi/canonical-idpsservice-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: 5
- target: $.paths['/api/v0/idps'].get
  update:
    x-apievangelist-phrasing:
      intent: List configured identity providers
      effect: read
      questions:
      - Which external identity providers are set up for sign-in?
      - Can I see every social or OIDC login provider configured in the admin?
      instructions:
      - text: List all configured identity providers.
      - text: Show me every login provider set up in the identity platform.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/idps'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an identity provider
      effect: write
      questions:
      - How do I connect a new OIDC identity provider for sign-in?
      - Can I configure Sign in with Apple using a team ID and private key?
      - Is it possible to set the scopes and claims requested from a new provider?
      instructions:
      - text: Add identity provider {provider} with client ID {client_id} and secret {client_secret}.
        slots:
          provider: requestBody.provider
          client_id: requestBody.client_id
          client_secret: requestBody.client_secret
      - text: Create an OIDC provider labeled {label} with issuer {issuer_url} and scopes {scope}.
        slots:
          label: requestBody.label
          issuer_url: requestBody.issuer_url
          scope: requestBody.scope
      - text: Set up an Apple login with team {apple_team_id} and key ID {apple_private_key_id}.
        slots:
          apple_team_id: requestBody.apple_team_id
          apple_private_key_id: requestBody.apple_private_key_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/idps/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one identity provider
      effect: read
      questions:
      - What client ID and issuer is a particular identity provider using?
      - Can I look up a single login provider by its ID?
      instructions:
      - text: Show identity provider {id}.
        slots:
          id: path.id
      - text: Get the configuration of login provider {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/idps/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an identity provider
      effect: destructive
      questions:
      - How do I disconnect a login provider users should no longer sign in with?
      - Can I delete an identity provider configuration?
      instructions:
      - text: Remove identity provider {id}.
        slots:
          id: path.id
      - text: Delete the login provider {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v0/idps/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an identity provider
      effect: write
      questions:
      - How do I rotate the client secret on an existing identity provider?
      - Can I change the scopes or mapper URL for a configured provider?
      instructions:
      - text: Update provider {id} with client secret {client_secret}.
        slots:
          id: path.id
          client_secret: requestBody.client_secret
      - text: Change identity provider {id} to request scopes {scope} and use mapper {mapper_url}.
        slots:
          id: path.id
          scope: requestBody.scope
          mapper_url: requestBody.mapper_url
      method: generated
      generated: '2026-09-26'