> ## Documentation Index > Fetch the complete documentation index at: https://docs.mcpblacksmith.com/llms.txt > Use this file to discover all available pages before exploring further. # Authentication > How generated MCP servers handle authentication — OAuth2, API keys, JWT, Bearer tokens, and more. ## Overview MCP Blacksmith auto-detects authentication requirements from your OpenAPI specification's [`securitySchemes`](/reference/oas-3-0#security-scheme-object) 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](/reference/oas-3-0#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. ```bash .env theme={null} 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. ```bash .env theme={null} BEARER_TOKEN=your-bearer-token ``` Sends `Authorization: Bearer your-bearer-token` with each request. ### HTTP Basic Used for username/password authentication. ```bash .env theme={null} BASIC_AUTH_USERNAME=your-username BASIC_AUTH_PASSWORD=your-password ``` Credentials are Base64-encoded and sent as `Authorization: Basic `. ### OAuth 2.0 Used for APIs requiring [OAuth2 flows](/reference/oas-3-0#oauth2-flows) (Authorization Code, Client Credentials, Password). ```bash .env theme={null} 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:/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. ```bash .env theme={null} 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. ```bash .env theme={null} # 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 ` 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: ```bash .env theme={null} 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](/reference/oas-3-1#security-scheme-object) for specification details. ```bash .env theme={null} 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: ```python theme={null} # 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