naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    UNKEY_ROOT_KEY: UNKEY_ROOT_KEY
capability:
  consumes:
  - type: http
    namespace: unkey
    baseUri: https://api.unkey.com
    description: Unkey platform API for key management, rate limiting, and identity operations
    authentication:
      type: bearer
      token: '{{UNKEY_ROOT_KEY}}'
    resources:
    - name: analytics
      path: /v2
      description: Analytics query operations for key verification data
      operations:
      - name: get-verifications
        method: POST
        description: Query Key Verification Data
        inputParameters:
        - name: query
          in: body
          type: string
          required: true
          description: SQL SELECT query against key verification analytics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            query: '{{tools.query}}'
    - name: apis
      path: /v2
      description: API namespace management operations
      operations:
      - name: create-api
        method: POST
        description: Create API Namespace
        inputParameters:
        - name: name
          in: body
          type: string
          required: true
          description: Name for the API namespace
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            name: '{{tools.name}}'
      - name: delete-api
        method: POST
        description: Delete API Namespace
        inputParameters:
        - name: apiId
          in: body
          type: string
          required: true
          description: ID of the API namespace to delete
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            apiId: '{{tools.apiId}}'
      - name: get-api
        method: POST
        description: Get API Namespace
        inputParameters:
        - name: apiId
          in: body
          type: string
          required: true
          description: ID of the API namespace to retrieve
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            apiId: '{{tools.apiId}}'
      - name: list-keys
        method: POST
        description: List API Keys
        inputParameters:
        - name: apiId
          in: body
          type: string
          required: true
          description: ID of the API namespace to list keys for
        - name: cursor
          in: body
          type: string
          required: false
          description: Pagination cursor
        - name: limit
          in: body
          type: integer
          required: false
          description: Maximum number of keys to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            apiId: '{{tools.apiId}}'
            cursor: '{{tools.cursor}}'
            limit: '{{tools.limit}}'
    - name: keys
      path: /v2
      description: API key lifecycle management operations
      operations:
      - name: create-key
        method: POST
        description: Create API Key
        inputParameters:
        - name: apiId
          in: body
          type: string
          required: true
          description: ID of the API namespace
        - name: prefix
          in: body
          type: string
          required: false
          description: Key prefix (e.g. sk, pk, test)
        - name: name
          in: body
          type: string
          required: false
          description: Human-readable name for the key
        - name: externalId
          in: body
          type: string
          required: false
          description: External user or organization identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            apiId: '{{tools.apiId}}'
            prefix: '{{tools.prefix}}'
            name: '{{tools.name}}'
            externalId: '{{tools.externalId}}'
      - name: verify-key
        method: POST
        description: Verify API Key
        inputParameters:
        - name: apiId
          in: body
          type: string
          required: false
          description: ID of the API namespace
        - name: key
          in: body
          type: string
          required: true
          description: The API key to verify
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            apiId: '{{tools.apiId}}'
            key: '{{tools.key}}'
      - name: get-key
        method: POST
        description: Get API Key
        inputParameters:
        - name: keyId
          in: body
          type: string
          required: true
          description: ID of the key to retrieve
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            keyId: '{{tools.keyId}}'
      - name: delete-key
        method: POST
        description: Delete API Keys
        inputParameters:
        - name: keyIds
          in: body
          type: array
          required: true
          description: List of key IDs to delete
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            keyIds: '{{tools.keyIds}}'
      - name: update-key
        method: POST
        description: Update Key Settings
        inputParameters:
        - name: keyId
          in: body
          type: string
          required: true
          description: ID of the key to update
        - name: name
          in: body
          type: string
          required: false
          description: New name for the key
        - name: enabled
          in: body
          type: boolean
          required: false
          description: Whether the key is enabled
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            keyId: '{{tools.keyId}}'
            name: '{{tools.name}}'
            enabled: '{{tools.enabled}}'
      - name: reroll-key
        method: POST
        description: Reroll Key
        inputParameters:
        - name: keyId
          in: body
          type: string
          required: true
          description: ID of the key to reroll
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            keyId: '{{tools.keyId}}'
      - name: add-permissions
        method: POST
        description: Add Key Permissions
        inputParameters:
        - name: keyId
          in: body
          type: string
          required: true
          description: ID of the key
        - name: permissions
          in: body
          type: array
          required: true
          description: Permissions to add to the key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            keyId: '{{tools.keyId}}'
            permissions: '{{tools.permissions}}'
      - name: add-roles
        method: POST
        description: Add Key Roles
        inputParameters:
        - name: keyId
          in: body
          type: string
          required: true
          description: ID of the key
        - name: roles
          in: body
          type: array
          required: true
          description: Roles to add to the key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            keyId: '{{tools.keyId}}'
            roles: '{{tools.roles}}'
      - name: whoami
        method: POST
        description: Get API Key by Hash
        inputParameters:
        - name: hash
          in: body
          type: string
          required: true
          description: Hash of the key to look up
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            hash: '{{tools.hash}}'
    - name: identities
      path: /v2
      description: Identity management for grouping keys by external user or organization
      operations:
      - name: create-identity
        method: POST
        description: Create Identity
        inputParameters:
        - name: externalId
          in: body
          type: string
          required: true
          description: External identifier for the identity
        - name: meta
          in: body
          type: object
          required: false
          description: Metadata to associate with the identity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            externalId: '{{tools.externalId}}'
            meta: '{{tools.meta}}'
      - name: get-identity
        method: POST
        description: Get Identity
        inputParameters:
        - name: identityId
          in: body
          type: string
          required: false
          description: ID of the identity
        - name: externalId
          in: body
          type: string
          required: false
          description: External ID of the identity
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            identityId: '{{tools.identityId}}'
      - name: list-identities
        method: POST
        description: List Identities
        inputParameters:
        - name: cursor
          in: body
          type: string
          required: false
          description: Pagination cursor
        - name: limit
          in: body
          type: integer
          required: false
          description: Maximum number of identities to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            cursor: '{{tools.cursor}}'
            limit: '{{tools.limit}}'
      - name: update-identity
        method: POST
        description: Update Identity
        inputParameters:
        - name: identityId
          in: body
          type: string
          required: true
          description: ID of the identity to update
        - name: meta
          in: body
          type: object
          required: false
          description: Updated metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            identityId: '{{tools.identityId}}'
            meta: '{{tools.meta}}'
      - name: delete-identity
        method: POST
        description: Delete Identity
        inputParameters:
        - name: identityId
          in: body
          type: string
          required: true
          description: ID of the identity to delete
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            identityId: '{{tools.identityId}}'
    - name: ratelimit
      path: /v2
      description: Standalone rate limiting operations
      operations:
      - name: limit
        method: POST
        description: Apply Rate Limiting
        inputParameters:
        - name: namespace
          in: body
          type: string
          required: true
          description: Namespace grouping rate limit rules
        - name: identifier
          in: body
          type: string
          required: true
          description: Unique identifier being rate limited (user ID, IP, etc.)
        - name: limit
          in: body
          type: integer
          required: true
          description: Maximum number of requests in the window
        - name: duration
          in: body
          type: integer
          required: true
          description: Window duration in milliseconds
        - name: cost
          in: body
          type: integer
          required: false
          description: Cost of this request (default 1)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            namespace: '{{tools.namespace}}'
            identifier: '{{tools.identifier}}'
            limit: '{{tools.limit}}'
            duration: '{{tools.duration}}'
            cost: '{{tools.cost}}'
      - name: multi-limit
        method: POST
        description: Apply Multiple Rate Limit Checks
        inputParameters:
        - name: limits
          in: body
          type: array
          required: true
          description: Array of rate limit checks to apply
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            limits: '{{tools.limits}}'
      - name: set-override
        method: POST
        description: Set Ratelimit Override
        inputParameters:
        - name: namespaceId
          in: body
          type: string
          required: false
          description: ID of the namespace
        - name: namespaceName
          in: body
          type: string
          required: false
          description: Name of the namespace
        - name: identifier
          in: body
          type: string
          required: true
          description: Identifier to override
        - name: limit
          in: body
          type: integer
          required: true
          description: Override limit
        - name: duration
          in: body
          type: integer
          required: true
          description: Override window duration
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            identifier: '{{tools.identifier}}'
            limit: '{{tools.limit}}'
            duration: '{{tools.duration}}'
      - name: get-override
        method: POST
        description: Get Ratelimit Override
        inputParameters:
        - name: namespaceId
          in: body
          type: string
          required: false
          description: ID of the namespace
        - name: identifier
          in: body
          type: string
          required: true
          description: Identifier to get override for
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            identifier: '{{tools.identifier}}'
      - name: list-overrides
        method: POST
        description: List Ratelimit Overrides
        inputParameters:
        - name: namespaceId
          in: body
          type: string
          required: false
          description: ID of the namespace
        - name: cursor
          in: body
          type: string
          required: false
          description: Pagination cursor
        - name: limit
          in: body
          type: integer
          required: false
          description: Maximum results to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            namespaceId: '{{tools.namespaceId}}'
      - name: delete-override
        method: POST
        description: Delete Ratelimit Override
        inputParameters:
        - name: namespaceId
          in: body
          type: string
          required: false
          description: ID of the namespace
        - name: identifier
          in: body
          type: string
          required: true
          description: Identifier to delete override for
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            identifier: '{{tools.identifier}}'
    - name: permissions
      path: /v2
      description: Permission and role management operations
      operations:
      - name: create-permission
        method: POST
        description: Create Permission
        inputParameters:
        - name: name
          in: body
          type: string
          required: true
          description: Name of the permission
        - name: description
          in: body
          type: string
          required: false
          description: Description of what the permission grants
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            name: '{{tools.name}}'
            description: '{{tools.description}}'
      - name: get-permission
        method: POST
        description: Get Permission
        inputParameters:
        - name: permissionId
          in: body
          type: string
          required: true
          description: ID of the permission to retrieve
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            permissionId: '{{tools.permissionId}}'
      - name: list-permissions
        method: POST
        description: List Permissions
        inputParameters:
        - name: cursor
          in: body
          type: string
          required: false
          description: Pagination cursor
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            cursor: '{{tools.cursor}}'
      - name: delete-permission
        method: POST
        description: Delete Permission
        inputParameters:
        - name: permissionId
          in: body
          type: string
          required: true
          description: ID of the permission to delete
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            permissionId: '{{tools.permissionId}}'
      - name: create-role
        method: POST
        description: Create Role
        inputParameters:
        - name: name
          in: body
          type: string
          required: true
          description: Name of the role
        - name: description
          in: body
          type: string
          required: false
          description: Description of the role
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            name: '{{tools.name}}'
            description: '{{tools.description}}'
      - name: get-role
        method: POST
        description: Get Role
        inputParameters:
        - name: roleId
          in: body
          type: string
          required: true
          description: ID of the role to retrieve
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            roleId: '{{tools.roleId}}'
      - name: list-roles
        method: POST
        description: List Roles
        inputParameters:
        - name: cursor
          in: body
          type: string
          required: false
          description: Pagination cursor
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            cursor: '{{tools.cursor}}'
      - name: delete-role
        method: POST
        description: Delete Role
        inputParameters:
        - name: roleId
          in: body
          type: string
          required: true
          description: ID of the role to delete
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            roleId: '{{tools.roleId}}'
    - name: liveness
      path: /v2
      description: Health check operations
      operations:
      - name: liveness
        method: GET
        description: Health Check
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.