OpenAPI Resource Import

Source Not Verified

This page describes the conceptual design of OpenAPI resource import. Implementation details and API specifications require verification against source code before production use.

Summary

OpenAPI Resource Import enables automatic discovery and creation of Keymate resources from OpenAPI (Swagger) specifications. Instead of manually defining each API endpoint as a resource, you provide an OpenAPI spec and Keymate extracts paths, operations, and security schemes to generate resources and scopes automatically.

Why It Exists

Manual resource creation does not scale for modern APIs:

• API sprawl — Microservice architectures have hundreds of endpoints across dozens of services
• Specification drift — API specs evolve faster than manual resource updates
• Human error — Manual entry leads to typos, missing endpoints, and inconsistent naming
• Onboarding friction — New services require tedious resource configuration before authorization works

OpenAPI import addresses these challenges by treating the API specification as the source of truth for authorization resources.

Where It Fits in Keymate

Boundaries

This concept covers:

• OpenAPI specification parsing
• Resource and scope generation from API paths
• Mapping HTTP methods to scopes
• Handling parameterized paths

This concept does not cover:

• Resource entity details → see Resource Model
• Scope definitions → see Scope Model
• Policy creation (not auto-generated from specs)

How It Works

Import Workflow

1. Provide OpenAPI specification — Upload or reference a URL to your OpenAPI 3.x or Swagger 2.x spec
2. Select target Resource Server — Choose or create the Resource Server that will own the imported resources
3. Configure mapping options — Define how paths become resource names and how operations map to scopes
4. Preview generated resources — Review the resources and scopes before creation
5. Execute import — Create resources and scopes in Keymate

Path to Resource Mapping

OpenAPI paths map directly to Keymate resources:

OpenAPI Path	Resource Name	Description
/users	/users	Collection endpoint
/users/{id}	/users/{id}	Single item endpoint
/users/{id}/orders	/users/{id}/orders	Nested resource

Operation to Scope Mapping

HTTP operations map to authorization scopes:

HTTP Method	Generated Scope	Typical Usage
GET	read	Retrieve resources
POST	create	Create new resources
PUT	update	Replace resources
PATCH	update	Partial update
DELETE	delete	Remove resources

For resource-specific scopes, the mapping includes the resource context:

Path + Method	Generated Scope
GET /users	users:read
POST /users	users:create
DELETE /users/{id}	users:delete

Security Scheme Integration

OpenAPI security schemes inform scope requirements:

paths:
  /orders:
    get:
      security:
        - oauth2:
            - orders:read

When security schemes reference OAuth scopes, Keymate can:

• Create matching scopes if they do not exist
• Link imported resources to the specified scopes
• Preserve the authorization requirements from the API spec

Handling Parameterized Paths

Path parameters ({id}, {userId}) are preserved in resource names, enabling wildcard matching:

/users/{id}         → Resource: /users/{id}
/users/{id}/profile → Resource: /users/{id}/profile
/orders/{orderId}   → Resource: /orders/{orderId}

Diagram

Example Scenario

Scenario

A developer imports a payment service OpenAPI specification to automatically create authorization resources for all payment-related endpoints.

Input

• Actor: API developer

• OpenAPI Spec: payment-service-openapi.yaml

• Target Resource Server: payment-api

• Context:

  OpenAPI excerpt:

  openapi: 3.0.0
  info:
    title: Payment Service API
    version: 1.0.0
  paths:
    /payments:
      get:
        operationId: listPayments
        security:
          - oauth2: [payments:read]
      post:
        operationId: createPayment
        security:
          - oauth2: [payments:create]
    /payments/{id}:
      get:
        operationId: getPayment
        security:
          - oauth2: [payments:read]
      delete:
        operationId: cancelPayment
        security:
          - oauth2: [payments:delete]
    /payments/{id}/refund:
      post:
        operationId: refundPayment
        security:
          - oauth2: [payments:refund]

Expected Outcome

• Result: 4 resources and 4 scopes created
• Generated Resources:
  • /payments with scopes payments:read, payments:create
  • /payments/{id} with scopes payments:read, payments:delete
  • /payments/{id}/refund with scope payments:refund
• Generated Scopes: payments:read, payments:create, payments:delete, payments:refund
• Why: The import process parsed all paths and operations, extracted security scheme references, and created corresponding Keymate resources and scopes.

Common Misunderstandings

• "Import creates policies automatically" — Import creates resources and scopes only. Policies defining who can access resources must be configured separately.

• "Existing resources are overwritten" — Import behavior for existing resources depends on configuration (skip, update, or fail). Review preview before executing.

• "All OpenAPI features are supported" — Import focuses on paths, operations, and security schemes. Custom extensions, callbacks, and webhooks may require manual resource creation.

warning

Importing a large OpenAPI specification creates many resources at once. Review the preview carefully and consider importing in batches for complex APIs.

Design Notes / Best Practices

• Keep specs up to date — Treat OpenAPI specs as the source of truth. Re-import when APIs change to keep resources synchronized.

• Use consistent operationIds — Well-named operationIds (createPayment, listOrders) improve generated resource readability.

• Define security schemes — Specs with explicit security schemes enable automatic scope creation and linking.

• Import to dedicated Resource Servers — Create a Resource Server per API service to maintain clear ownership and isolation.

tip

Use preview mode before executing imports to verify resource names and scope mappings match your authorization model expectations.

Related Use Cases

• Onboarding new microservices to Keymate authorization
• Synchronizing resources with API specification changes
• Bulk resource creation for API-first development
• Auditing API coverage against authorization resources

Related Docs

Resource Model

Resource entity structure and metadata

Scope Model

Action definitions and scope types

Admin Console

UI for resource management

Integration Hub

External system connectors

FAQ

Which OpenAPI versions are supported?

OpenAPI 3.0.x and 3.1.x are the primary targets. Swagger 2.x (OpenAPI 2.0) may be supported with limited features.

Can I import from a URL instead of uploading a file?

URL-based import enables continuous synchronization with published API specs. Check Admin Console documentation for supported URL formats.

What happens to resources when I re-import an updated spec?

Re-import behavior depends on configuration: new resources can be added, existing resources updated, or conflicts flagged for manual resolution.

Are custom OpenAPI extensions (x-*) processed?

Custom extensions may be used for additional metadata like resource categories or tags. Check the import configuration for supported extension mappings.