Kong Agent Onboarding

naftiko: 1.0.0-alpha2
info:
  label: Kong Agent Onboarding
  description: 'Kong Agent Onboarding — automated agent self-registration on Kong Enterprise Admin API.
    Verifies Web Bot Auth signatures (RFC 9421) against a trusted-issuer policy, composes Kong consumer +
    consumer_group + key-auth operations into a single scoped-credential issuance, and emits an audit
    event recording the agent identity, consent acknowledgement, and resulting credential. Companion to
    the API Evangelist agent-onboarding pattern. Runtime policy enforcement (signature verify, consent check, scope classify, audit emit) lives in the orchestration.steps below — each step that gates issuance carries on_failure: deny. Lint-time validation of this capability shape lives in the companion Polychro ruleset at https://github.com/api-evangelist/posts/blob/main/polychro/agent-onboarding-rules.yaml — Polychro is Naftiko''s governance layer, separate from the capability spec, and is the correct home for cross-object consistency rules that apply across every agent-onboarding capability.'
  tags:
  - Kong
  - Agent Onboarding
  - Web Bot Auth
  - RFC 9421
  - RFC 7591
  - MCP
  - Naftiko Capability
  - Agent Skills
  created: '2026-05-27'
  modified: '2026-05-27'
  related:
  - https://apievangelist.com/2026/05/27/automated-agent-onboarding-is-a-naftiko-capability-not-a-gateway-feature/
  - https://github.com/api-evangelist/kong
binds:
- namespace: env
  keys:
    KONG_API_KEY: KONG_API_KEY
    KONG_ADMIN_BASE_URI: KONG_ADMIN_BASE_URI
    AGENT_TRUSTED_ISSUERS: AGENT_TRUSTED_ISSUERS
    AGENT_CONSENT_DOC_URL: AGENT_CONSENT_DOC_URL
    AGENT_CONSENT_HASH: AGENT_CONSENT_HASH

capability:

  # ============================================================================
  # CONSUMES — upstream Kong Enterprise Admin API operations that this
  # capability composes to provision an agent's scoped credential.
  # ============================================================================
  consumes:
  - type: http
    namespace: kong-admin
    baseUri: '{{env.KONG_ADMIN_BASE_URI}}'
    description: Kong Enterprise Admin API — the four operations needed to provision a scoped
      consumer + group + key-auth credential for a verified agent identity.
    resources:

    - name: workspace-consumers
      path: /{workspace}/consumers
      operations:
      - name: createconsumer
        method: POST
        description: Create a Kong consumer record for the agent identity.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: workspace
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: '{ username, custom_id, tags }'
          required: true

    - name: workspace-consumer-groups
      path: /{workspace}/consumer_groups
      operations:
      - name: createconsumergroup
        method: POST
        description: Create a consumer_group representing the agent's scope tier.
          Idempotent — only invoked if the policy-declared tier doesn't already exist.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: workspace
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: '{ name, tags }'
          required: true

    - name: workspace-consumer-group-consumers
      path: /{workspace}/consumer_groups/{ConsumerGroupId}/consumers
      operations:
      - name: addconsumertoconsumergroup
        method: POST
        description: Bind the agent's consumer to the scope-tier consumer_group, inheriting
          its plugins (ACL, rate-limiting, request-validation).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: workspace
          in: path
          type: string
          required: true
        - name: ConsumerGroupId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: '{ consumer: { id } }'
          required: true

    - name: workspace-consumer-key-auth
      path: /{workspace}/consumers/{ConsumerIdForNestedEntities}/key-auth
      operations:
      - name: createkeyauth
        method: POST
        description: Mint the scoped API key for the agent. The returned `key` value is what
          the agent uses on subsequent calls; this value is returned to the agent exactly once.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: workspace
          in: path
          type: string
          required: true
        - name: ConsumerIdForNestedEntities
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: '{ key, ttl, tags }'
          required: false
      - name: deletekeyauth
        method: DELETE
        description: Revoke the agent's API key. Invoked when the agent calls its
          revocation_url.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.

    - name: workspace-event-gateways-audit-produce
      path: /v1/event-gateways/{gatewayId}/topics/agent-audit/produce
      operations:
      - name: emitauditevent
        method: POST
        description: Emit an audit event to the Kong Event Gateway agent-audit topic recording
          the agent identity, the Web Bot Auth signature, the consent hash, the issued
          credential id, and the policy decision.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: gatewayId
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          required: true

    authentication:
      type: apikey
      key: Kong-Admin-Token
      value: '{{env.KONG_API_KEY}}'
      placement: header

  # ============================================================================
  # ORCHESTRATION — the multi-step flow that composes the consumed operations
  # into a single agent-onboarding business operation. Steps execute in order;
  # outputs of earlier steps are referenced by later steps via `${steps.<id>.<jsonpath>}`.
  # ============================================================================
  orchestration:
  - name: onboard-agent
    description: End-to-end agent onboarding — verify signature, ensure scope tier exists,
      provision consumer + group binding + key, emit audit, return credential.
    inputs:
    - name: signature
      type: object
      description: RFC 9421 HTTP Message Signature headers from the agent's request.
      required: true
    - name: signature_agent
      type: string
      description: Agent issuer (e.g., 'https://claude.ai/').
      required: true
    - name: skill_id
      type: string
      required: true
    - name: requested_scopes
      type: array
      required: true
    - name: consent_hash
      type: string
      required: true
    - name: contact
      type: object
      description: '{ operator, support_url, purpose }'
      required: true

    steps:

    - id: verify_signature
      type: builtin.web-bot-auth.verify
      description: Verify the RFC 9421 signature against the operator's published key directory.
      with:
        signature: ${input.signature}
        agent: ${input.signature_agent}
        trusted_issuers: '{{env.AGENT_TRUSTED_ISSUERS}}'
      on_failure: deny

    - id: verify_consent
      type: builtin.policy.assert
      description: Confirm the consent_hash matches the provider's currently-published consent document.
      with:
        assert: '${input.consent_hash} == {{env.AGENT_CONSENT_HASH}}'
      on_failure: deny

    - id: classify_scopes
      type: builtin.policy.scope-classify
      description: Map each requested scope to (auto-issue | approval-required | forbidden)
        per the provider's declared policy.
      with:
        requested: ${input.requested_scopes}
      output:
        auto: array
        approval: array
        forbidden: array
      on:
      - when: '${steps.classify_scopes.forbidden.length > 0}'
        do: deny
      - when: '${steps.classify_scopes.approval.length > 0}'
        do: defer-to-approval-webhook

    - id: create_consumer
      call: kong-admin.createconsumer
      description: Create the Kong consumer record for this agent.
      with:
        workspace: 'default'
        body:
          username: 'agent-${steps.verify_signature.agent_id}'
          custom_id: ${steps.verify_signature.agent_id}
          tags:
          - 'agent'
          - 'operator:${input.contact.operator}'
          - 'skill:${input.skill_id}'

    - id: ensure_consumer_group
      type: builtin.upsert
      description: Ensure the scope-tier consumer_group exists; idempotent.
      with:
        check_path: '/default/consumer_groups/${steps.classify_scopes.auto[0]}'
        create_call: kong-admin.createconsumergroup
        create_with:
          workspace: 'default'
          body:
            name: ${steps.classify_scopes.auto[0]}
            tags:
            - 'agent-scope-tier'

    - id: bind_consumer_to_group
      call: kong-admin.addconsumertoconsumergroup
      description: Bind the new consumer into the scope-tier group (inheriting plugins).
      with:
        workspace: 'default'
        ConsumerGroupId: ${steps.ensure_consumer_group.id}
        body:
          consumer:
            id: ${steps.create_consumer.id}

    - id: mint_credential
      call: kong-admin.createkeyauth
      description: Mint the scoped API key the agent will use. The key value is returned to
        the agent exactly once in the orchestration output and never logged at rest.
      with:
        workspace: 'default'
        ConsumerIdForNestedEntities: ${steps.create_consumer.id}
        body:
          ttl: 2592000   # 30 days; provider policy can override
          tags:
          - 'agent-credential'
          - 'operator:${input.contact.operator}'

    - id: emit_audit
      call: kong-admin.emitauditevent
      description: Record the onboarding act on the Event Gateway audit topic.
      with:
        gatewayId: 'default'
        body:
          event_type: 'agent.onboarded'
          agent_id: ${steps.verify_signature.agent_id}
          operator: ${input.contact.operator}
          support_url: ${input.contact.support_url}
          purpose: ${input.contact.purpose}
          skill_id: ${input.skill_id}
          scopes: ${steps.classify_scopes.auto}
          consent_hash: ${input.consent_hash}
          signature_keyid: ${steps.verify_signature.keyid}
          credential_id: ${steps.mint_credential.id}

    output:
      agent_id: ${steps.verify_signature.agent_id}
      consumer_id: ${steps.create_consumer.id}
      consumer_group_id: ${steps.ensure_consumer_group.id}
      credential:
        type: 'Bearer'
        value: ${steps.mint_credential.key}
        expires_at: ${steps.mint_credential.expires_at}
        revocation_url: '/v1/agents/${steps.verify_signature.agent_id}/revoke'
      scopes: ${steps.classify_scopes.auto}
      rate_limit: ${steps.ensure_consumer_group.rate_limit}
      audit_id: ${steps.emit_audit.id}
      terms_acknowledged: ${input.consent_hash}

  - name: revoke-agent
    description: Revoke an issued credential when the agent calls revocation_url.
    inputs:
    - name: agent_id
      type: string
      required: true
    - name: credential_id
      type: string
      required: true
    steps:
    - id: delete_key
      call: kong-admin.deletekeyauth
      with:
        workspace: 'default'
        ConsumerIdForNestedEntities: ${input.agent_id}
        KeyAuthId: ${input.credential_id}
    - id: emit_revoke_audit
      call: kong-admin.emitauditevent
      with:
        gatewayId: 'default'
        body:
          event_type: 'agent.revoked'
          agent_id: ${input.agent_id}
          credential_id: ${input.credential_id}
    output:
      revoked: true
      audit_id: ${steps.emit_revoke_audit.id}

  # ============================================================================
  # EXPOSES — downstream surfaces this capability publishes for agent and
  # human consumers. The /v1/agents/onboard REST endpoint and the
  # agent.register MCP tool both call the onboard-agent orchestration above.
  # ============================================================================
  exposes:
  - type: rest
    namespace: kong-agent-onboarding-rest
    port: 8080
    description: REST surface for automated agent onboarding. Verifies Web Bot Auth signatures
      on inbound requests; one round trip from request to issued credential for auto-issuable scopes.
    resources:
    - path: /v1/agents/onboard
      name: agents-onboard
      description: Agent self-registration endpoint.
      operations:
      - method: POST
        name: onboardagent
        description: Verify the agent's Web Bot Auth signature, check the requested scopes
          against the declared policy, provision the Kong credential, and return it.
        call: orchestration.onboard-agent
        with:
          signature: rest.headers.signature
          signature_agent: rest.headers.signature-agent
          skill_id: rest.body.skill_id
          requested_scopes: rest.body.scopes
          consent_hash: rest.body.consent_hash
          contact: rest.body.contact
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/agents/{agent_id}/revoke
      name: agents-revoke
      description: Revoke the credential issued during onboarding.
      operations:
      - method: POST
        name: revokeagent
        description: Revoke an issued credential.
        call: orchestration.revoke-agent
        with:
          agent_id: rest.agent_id
          credential_id: rest.body.credential_id

  - type: mcp
    namespace: kong-agent-onboarding-mcp
    port: 9090
    transport: http
    description: MCP surface for agent onboarding. Exposes agent.register and agent.revoke
      as tools an MCP client can call directly.
    tools:
    - name: agent-register
      description: Register an agent with the Kong-backed API surface and obtain a scoped API key.
        Requires a verified Web Bot Auth signature.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: orchestration.onboard-agent
      with:
        signature: tools.signature
        signature_agent: tools.signature_agent
        skill_id: tools.skill_id
        requested_scopes: tools.requested_scopes
        consent_hash: tools.consent_hash
        contact: tools.contact
      outputParameters:
      - type: object
        mapping: $.
    - name: agent-revoke
      description: Revoke an issued agent credential.
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: orchestration.revoke-agent
      with:
        agent_id: tools.agent_id
        credential_id: tools.credential_id

  - type: agent-skill
    namespace: kong-agent-onboarding-skills
    description: Agent skill published at /skills/onboard-agent.md. The skill is the
      published operating manual that tells a compatible agent how to construct the
      onboarding request — including how to compute the consent hash, sign the request
      per RFC 9421, and handle 202-Accepted approval-deferred responses.
    skill:
      name: onboard-agent
      description: Register this agent with the API provider and obtain a scoped credential.
      file: skills/onboard-agent.md