Unkey API Key Management

naftiko: "1.0.0-alpha1"

info:
  label: Unkey API Key Management
  description: >-
    Workflow capability for managing the full lifecycle of API keys using the Unkey
    platform. Covers creating, verifying, updating, rotating, and revoking keys, plus
    managing permissions and roles for fine-grained access control. Used by platform
    engineers and API providers to issue and govern access to their APIs.
  tags:
    - Unkey
    - API Keys
    - Access Control
    - Developer Platform
    - Authentication
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      UNKEY_ROOT_KEY: UNKEY_ROOT_KEY

capability:
  consumes:
    - import: unkey
      location: ./shared/unkey.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: unkey-key-management-api
      description: Unified REST API for Unkey API key lifecycle management.
      resources:
        - path: /v1/apis
          name: apis
          description: API namespace management
          operations:
            - method: POST
              name: create-api
              description: Create a new API namespace
              call: "unkey.create-api"
              with:
                name: "rest.name"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: get-api
              description: Get an API namespace by ID
              call: "unkey.get-api"
              with:
                apiId: "rest.apiId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/apis/{apiId}/keys
          name: api-keys
          description: Keys within an API namespace
          operations:
            - method: GET
              name: list-keys
              description: List all keys in an API namespace
              call: "unkey.list-keys"
              with:
                apiId: "rest.apiId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-key
              description: Create a new API key
              call: "unkey.create-key"
              with:
                apiId: "rest.apiId"
                name: "rest.name"
                externalId: "rest.externalId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/keys/{keyId}
          name: key
          description: Single key operations
          operations:
            - method: GET
              name: get-key
              description: Get an API key by ID
              call: "unkey.get-key"
              with:
                keyId: "rest.keyId"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: update-key
              description: Update key settings
              call: "unkey.update-key"
              with:
                keyId: "rest.keyId"
                name: "rest.name"
                enabled: "rest.enabled"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: DELETE
              name: delete-key
              description: Delete an API key
              call: "unkey.delete-key"
              with:
                keyIds: "rest.keyId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/keys/{keyId}/verify
          name: key-verify
          description: Verify an API key
          operations:
            - method: POST
              name: verify-key
              description: Verify a key and return its validity and metadata
              call: "unkey.verify-key"
              with:
                key: "rest.key"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/keys/{keyId}/reroll
          name: key-reroll
          description: Rotate an API key
          operations:
            - method: POST
              name: reroll-key
              description: Rotate (reroll) a key to generate a new value
              call: "unkey.reroll-key"
              with:
                keyId: "rest.keyId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/keys/{keyId}/permissions
          name: key-permissions
          description: Key permission management
          operations:
            - method: POST
              name: add-permissions
              description: Add permissions to a key
              call: "unkey.add-permissions"
              with:
                keyId: "rest.keyId"
                permissions: "rest.permissions"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/keys/{keyId}/roles
          name: key-roles
          description: Key role management
          operations:
            - method: POST
              name: add-roles
              description: Add roles to a key
              call: "unkey.add-roles"
              with:
                keyId: "rest.keyId"
                roles: "rest.roles"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/permissions
          name: permissions
          description: Permission management
          operations:
            - method: POST
              name: create-permission
              description: Create a new permission
              call: "unkey.create-permission"
              with:
                name: "rest.name"
                description: "rest.description"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-permissions
              description: List all permissions
              call: "unkey.list-permissions"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/roles
          name: roles
          description: Role management
          operations:
            - method: POST
              name: create-role
              description: Create a new role
              call: "unkey.create-role"
              with:
                name: "rest.name"
                description: "rest.description"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: GET
              name: list-roles
              description: List all roles
              call: "unkey.list-roles"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: unkey-key-management-mcp
      transport: http
      description: MCP server for AI-assisted API key lifecycle management with Unkey.
      tools:
        - name: create-api-namespace
          description: Create a new API namespace in Unkey for organizing keys
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "unkey.create-api"
          with:
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-api-keys
          description: List all API keys within an API namespace
          hints:
            readOnly: true
            openWorld: false
          call: "unkey.list-keys"
          with:
            apiId: "tools.apiId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-api-key
          description: Create a new API key with optional prefix, name, roles, and rate limits
          hints:
            readOnly: false
            destructive: false
          call: "unkey.create-key"
          with:
            apiId: "tools.apiId"
            prefix: "tools.prefix"
            name: "tools.name"
            externalId: "tools.externalId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: verify-api-key
          description: Verify an API key and return its validity, permissions, rate limit status
          hints:
            readOnly: true
            openWorld: false
          call: "unkey.verify-key"
          with:
            key: "tools.key"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-api-key
          description: Retrieve full details of an API key by its ID
          hints:
            readOnly: true
            openWorld: false
          call: "unkey.get-key"
          with:
            keyId: "tools.keyId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: update-api-key
          description: Update an API key's name, metadata, rate limits, or enabled status
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "unkey.update-key"
          with:
            keyId: "tools.keyId"
            name: "tools.name"
            enabled: "tools.enabled"
          outputParameters:
            - type: object
              mapping: "$."
        - name: delete-api-key
          description: Permanently delete one or more API keys
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: "unkey.delete-key"
          with:
            keyIds: "tools.keyIds"
          outputParameters:
            - type: object
              mapping: "$."
        - name: reroll-api-key
          description: Rotate an API key to generate a new key value while preserving settings
          hints:
            readOnly: false
            destructive: false
          call: "unkey.reroll-key"
          with:
            keyId: "tools.keyId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: add-key-permissions
          description: Add permissions to an existing API key
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "unkey.add-permissions"
          with:
            keyId: "tools.keyId"
            permissions: "tools.permissions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: add-key-roles
          description: Add roles to an existing API key
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "unkey.add-roles"
          with:
            keyId: "tools.keyId"
            roles: "tools.roles"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-permission
          description: Create a new permission definition in the workspace
          hints:
            readOnly: false
            destructive: false
          call: "unkey.create-permission"
          with:
            name: "tools.name"
            description: "tools.description"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-permissions
          description: List all permissions in the workspace
          hints:
            readOnly: true
            openWorld: false
          call: "unkey.list-permissions"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-role
          description: Create a new role grouping multiple permissions
          hints:
            readOnly: false
            destructive: false
          call: "unkey.create-role"
          with:
            name: "tools.name"
            description: "tools.description"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-roles
          description: List all roles in the workspace
          hints:
            readOnly: true
            openWorld: false
          call: "unkey.list-roles"
          outputParameters:
            - type: object
              mapping: "$."