Skip to main content

​
Overview

MCP Blacksmith auto-detects authentication requirements from your OpenAPI specification’s securitySchemes and generates the appropriate handlers. You only need to provide credentials in the .env file. Each operation is mapped to its required authentication scheme via the Security Requirement object. The server automatically injects the correct credentials into every request.

​
Supported authentication types

​
API Key

Used when the API requires a key passed as a header, query parameter, or cookie.
.env
API_KEY=your-api-key-here
The generated code reads the key location (header, query, or cookie) and parameter name from the specification. For example, if the specification defines an API key in the X-API-Key header, the server automatically sends: 
X-API-Key: your-api-key-here

​
Bearer Token

Used for APIs that accept a static token in the Authorization header.
.env
BEARER_TOKEN=your-bearer-token
Sends Authorization: Bearer your-bearer-token with each request.

​
HTTP Basic

Used for username/password authentication.
.env
BASIC_AUTH_USERNAME=your-username
BASIC_AUTH_PASSWORD=your-password
Credentials are Base64-encoded and sent as Authorization: Basic <encoded>.

​
OAuth 2.0

Used for APIs requiring OAuth2 flows (Authorization Code, Client Credentials, Password).
.env
OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_SCOPES=scope1,scope2
How it works:
  1. On first run, the server opens your browser for authorization
  2. You authorize the application on the API provider’s consent page
  3. The server receives the authorization code via a local callback server
  4. Tokens are exchanged and saved to oauth2_tokens.json
  5. On subsequent runs, saved tokens are reused
  6. Expired tokens are automatically refreshed
Delete oauth2_tokens.json to force re-authorization if your tokens become invalid.
The callback server runs on port 8080 by default. Change OAUTH2_CALLBACK_PORT in .env if needed — make sure the matching redirect URI (http://localhost:<port>/callback) is registered in your OAuth provider’s developer console.

​
Flow selection

When an OpenAPI specification defines multiple OAuth2 flows on the same security scheme, the generator picks a single flow based on security strength:
  1. Authorization Code — most secure; requires user authorization via browser redirect
  2. Client Credentials — server-to-server; no user interaction
  3. Device Authorization — for headless/CLI devices (OAS 3.2+)
  4. Password — legacy; sends credentials directly
  5. Implicit — deprecated in OAuth 2.1; least secure
The generated .env and authentication class reflect only the selected flow. For example, a specification offering both authorizationCode and implicit flows will generate an Authorization Code handler — the implicit flow is discarded. If you need a different flow than the one selected, you can override the authentication configuration in the generation dashboard before generating your server.

​
OpenID Connect (OIDC)

Extends OAuth2 with ID token validation and automatic discovery.
.env
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_SCOPES=openid,profile,email
Works the same as OAuth2 with additional:
  • Automatic discovery from the OIDC Discovery endpoint
  • ID token validation
  • Tokens saved to oidc_tokens.json

​
JWT Bearer

Used for APIs that require dynamically signed JSON Web Tokens — such as GitHub Apps, Google service accounts, and Apple APIs. Detected when the OpenAPI spec declares bearerFormat: JWT on an HTTP Bearer scheme.
.env
# Required
JWT_PRIVATE_KEY=mcp-blacksmith-test.pem
JWT_ISSUER_ID=123456

# Optional (leave empty if not needed)
JWT_ALGORITHM=RS256
JWT_EXPIRY=600
JWT_AUDIENCE=
JWT_KEY_ID=
JWT_TOKEN_URL=
JWT_SCOPES=
JWT_PRIVATE_KEY accepts either a path to a .pem file (relative to the server directory or absolute) or an inline PEM key with newlines encoded as \n. How it works:
  1. The server reads the private key and issuer ID from .env
  2. Before each API request, a short-lived JWT is signed locally (RS256 by default)
  3. The JWT is sent as Authorization: Bearer <signed-jwt>
  4. Tokens are cached in memory and regenerated when near expiry (30-second buffer)
No browser flow or token file is needed — the private key acts as the permanent credential.

​
Token exchange variant

Some APIs (e.g. Google) require an additional step: the signed JWT is exchanged at a token endpoint for an access token. Set JWT_TOKEN_URL to enable this:
.env
JWT_TOKEN_URL=https://oauth2.googleapis.com/token
JWT_SCOPES=https://www.googleapis.com/auth/cloud-platform
When JWT_TOKEN_URL is set, the server POSTs the signed JWT to that endpoint and uses the returned access token instead.

​
Mutual TLS (mTLS)

Used for APIs requiring client certificate authentication. See mutualTLS in OAS 3.1 for specification details.
.env
MTLS_CERT_PATH=/path/to/client-cert.pem
MTLS_KEY_PATH=/path/to/client-key.pem
MTLS_CA_CERT_PATH=/path/to/ca-cert.pem
The HTTP client is configured with the client certificate for mutual authentication. If paths are not set, mTLS is disabled and a warning is logged.

​
Per-operation authentication

Not every operation uses the same authentication. The generated server maps each operation to its required schemes: 
# Generated in _auth.py
OPERATION_AUTH_MAP = {
    "list_users": [["oauth2"], ["api_key"]],   # Use oauth2 OR api_key
    "create_user": [["oauth2"]],                # OAuth2 only
    "get_public_info": [],                      # No authentication required
}
  • Outer list = OR — any one of these options works
  • Inner list = AND — all schemes in this group are required together
The server automatically selects the first available authentication option based on which credentials you’ve configured.

​
Security best practices

Never commit your .env file to version control. Add it to .gitignore.
  • Store credentials in the .env file, not in code
  • Use the minimum required scopes for OAuth2/OIDC
  • Replace API keys and tokens periodically
  • For multi-tenant deployments, add proper isolation and credentials management — or let us handle it with MCP Armory