Overview

Docs Kit automatically handles authentication for API endpoints based on OpenAPI security schemes. Configure security schemes in your spec, and the Try It modal will provide appropriate authentication inputs.

Security Schemes

Define security schemes in the components.securitySchemes section of your OpenAPI spec:

{
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

Supported Auth Types

API Key Authentication

API keys can be passed in headers, query parameters, or cookies.

Header-Based

{
  "securitySchemes": {
    "ApiKeyHeader": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "API key from dashboard"
    }
  }
}

Usage in Try It:

X-API-Key: sk_live_abc123def456

Query Parameter

{
  "securitySchemes": {
    "ApiKeyQuery": {
      "type": "apiKey",
      "in": "query",
      "name": "api_key"
    }
  }
}

Usage in Try It:

GET /api/users?api_key=sk_live_abc123def456

Cookie-Based

{
  "securitySchemes": {
    "ApiKeyCookie": {
      "type": "apiKey",
      "in": "cookie",
      "name": "api_key"
    }
  }
}

Usage in Try It:

Cookie: api_key=sk_live_abc123def456

Bearer Token (JWT)

For JWT tokens and OAuth 2.0 bearer tokens:

{
  "securitySchemes": {
    "BearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT",
      "description": "JWT token from /auth/login endpoint"
    }
  }
}

Usage in Try It:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Basic Authentication

Username and password authentication:

{
  "securitySchemes": {
    "BasicAuth": {
      "type": "http",
      "scheme": "basic",
      "description": "Username and password"
    }
  }
}

Usage in Try It:

Users enter username and password separately. Docs Kit automatically encodes to Base64:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

OAuth 2.0

Various OAuth 2.0 flows:

{
  "securitySchemes": {
    "OAuth2": {
      "type": "oauth2",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://auth.example.com/oauth/authorize",
          "tokenUrl": "https://auth.example.com/oauth/token",
          "scopes": {
            "read": "Read access",
            "write": "Write access",
            "admin": "Admin access"
          }
        }
      }
    }
  }
}

OpenID Connect

{
  "securitySchemes": {
    "OpenID": {
      "type": "openIdConnect",
      "openIdConnectUrl": "https://auth.example.com/.well-known/openid-configuration"
    }
  }
}

Applying Security to Endpoints

Global Security

Apply security to all endpoints:

{
  "security": [
    {
      "BearerAuth": []
    }
  ]
}

All endpoints require Bearer authentication unless overridden.

Per-Endpoint Security

Override security for specific endpoints:

{
  "paths": {
    "/public/health": {
      "get": {
        "summary": "Health check",
        "security": [],
        "responses": {...}
      }
    },
    "/users": {
      "get": {
        "summary": "List users",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {...}
      }
    }
  }
}

The /public/health endpoint requires no authentication (empty array), while /users requires Bearer token.

Multiple Auth Options

Allow multiple authentication methods:

{
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {...}
      }
    }
  }
}

Users can authenticate with either Bearer token OR API key.

Required Scopes

For OAuth 2.0, specify required scopes:

{
  "paths": {
    "/admin/users": {
      "delete": {
        "summary": "Delete user (admin only)",
        "security": [
          {
            "OAuth2": ["admin", "write"]
          }
        ],
        "responses": {...}
      }
    }
  }
}

Requires both admin and write scopes.

Try It Modal Integration

Authentication Tab

The Try It modal displays an "Authentication" tab showing all required security schemes for the endpoint.

Input Fields

Based on auth type, appropriate input fields appear:

API Key:

���������������������������������
 X-API-Key                       
 ����������������������������� 
  sk_live_abc123...            
 ����������������������������� 
���������������������������������

Bearer Token:

���������������������������������
 Bearer Token                    
 ����������������������������� 
  eyJhbGc...                   
 ����������������������������� 
���������������������������������

Basic Auth:

���������������������������������
 Username                        
 ����������������������������� 
  john@example.com             
 ����������������������������� 
                                 
 Password                        
 ����������������������������� 
  """"""""                     
 ����������������������������� 
���������������������������������

Persistence

Authentication values are saved in browser localStorage and persist across:

• Page reloads
• Navigation between endpoints
• Browser sessions

Users don't need to re-enter credentials repeatedly.

Security Best Practices

Use Descriptions

Add helpful descriptions to security schemes:

{
  "securitySchemes": {
    "ApiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "API key from your dashboard. Go to Settings > API Keys to generate a new key."
    }
  }
}

Descriptions appear as helper text in the Try It modal.

Specify bearerFormat

For bearer tokens, specify the format:

{
  "securitySchemes": {
    "BearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
}

Helps users understand what type of token is expected.

Document Scope Requirements

For OAuth 2.0, clearly document what each scope allows:

{
  "securitySchemes": {
    "OAuth2": {
      "type": "oauth2",
      "flows": {
        "authorizationCode": {
          "scopes": {
            "read": "Read user data and public resources",
            "write": "Create and update resources",
            "delete": "Delete resources (requires admin review)",
            "admin": "Full admin access to all resources"
          }
        }
      }
    }
  }
}

Use Appropriate Schemes

Choose the right auth method for your use case:

• API Keys - Simple, good for server-to-server
• Bearer/JWT - Modern, stateless, ideal for SPAs
• OAuth 2.0 - Third-party app authorization
• Basic Auth - Simple but requires HTTPS
• OpenID Connect - Identity and authentication

Example Configurations

Simple API Key

{
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ]
}

JWT with Optional API Key

{
  "components": {
    "securitySchemes": {
      "JWT": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "JWT": []
    },
    {
      "ApiKey": []
    }
  ]
}

Users can authenticate with either JWT OR API key.

OAuth 2.0 with Scopes

{
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://auth.example.com/authorize",
            "tokenUrl": "https://auth.example.com/token",
            "scopes": {
              "read": "Read access",
              "write": "Write access"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/users": {
      "get": {
        "security": [{ "OAuth2": ["read"] }]
      },
      "post": {
        "security": [{ "OAuth2": ["write"] }]
      }
    }
  }
}

Testing Authentication

Use the Try It modal to test authentication:

---

You've completed the Docs Kit documentation! Start building your documentation site with these guides.