Authentication

Authentication protects management endpoints and the MCP transport from unauthorized access.

HTTP authentication

HTTP authentication is enabled when API_AUTH_TOKEN is not empty. Send the admin credential or an API token in the Authorization header:

Authorization: Bearer <token>

The admin credential has access to every authenticated route. API tokens are scoped to mcp, metrics, or logs:

Route	Required credential
/mcp/	Admin credential or mcp scope
/metrics	Admin credential or metrics scope
/api/logs/recent, /api/logs/stream	Admin credential or logs scope
Registry, direct invoke, cache, and token routes	Admin credential
/mcp/health	Always open

When authentication is disabled, HTTP routes keep their open-mode behavior. Guarded tools still deny calls without a verified identity. stdio remains available for open tools only; it does not provide an identity for guarded tools.

Production deployment

Set API_AUTH_TOKEN before exposing the HTTP server outside a trusted network. Open mode is intended for local development and keeps management routes unauthenticated.

Outbound ERP authentication

When a tool executes, the connector authenticates to the upstream ERP using the spec.security block of the tool schema.

authType	Header sent	Use case
api-key	Authorization: <key>	Simple API keys; also accepts Frappe token key:secret.
basic	Authorization: Basic <base64(key)>	Basic HTTP auth.
bearer	Authorization: Bearer <key>	OAuth2 / bearer tokens.

Credential resolution — credentialRef names an environment variable on the server. The connector reads os.Getenv(credentialRef) and uses that value as the key. If a non-empty reference is unset, the tool call fails closed. An empty reference means that the tool sends no outbound authentication.

Tool schema — outbound auth

"spec": {
  "execution": {
    "type": "http",
    "method": "GET",
    "endpoint": "https://erp.example.com/api/v1/resource/Employee"
  },
  "security": {
    "authType": "bearer",
    "credentialRef": "ERP_API_TOKEN"
  }
}

Secrets stay out of the registry

Never put the secret value in the schema. Always reference it through credentialRef so it resolves from the server environment.

Data redaction

The logger automatically masks sensitive values before they reach console output, broadcast streams, or MCP log streams:

• Redacted keys: password, token, api_key, secret, authorization, ssn, national_id, bank_account, plus field prefixes Secret/Private and struct tags secret/pii/masq.
• Sensitive types: APIToken, Password, AuthHeader, SecretKey, PII.
• Regex masking: any Bearer <value> becomes Bearer [REDACTED].

API tokens

Token-based authentication has two credential classes:

Token class	Source	Scopes	Purpose
Admin token	API_AUTH_TOKEN environment variable	all (implicit)	Server administration, CLI operations
API tokens	api_tokens store (created via the control plane)	mcp, metrics, logs	MCP clients, monitoring, log access

Key properties:

• API token values are shown once at creation, prefixed erpbt_; only a SHA-256 hash is stored.
• Tokens can be scoped (mcp | metrics | logs), expire, and be revoked individually.
• When API_AUTH_TOKEN is set, protected routes return 401 for missing or invalid credentials and 403 for insufficient scope.
• API_AUTH_ADMIN_ROLES assigns verified roles to the admin identity.

See the API token guide for lifecycle requests and CLI usage.

Role-protected tools

Tools opt into authorization with spec.security.allowedRoles. Roles must match [a-z][a-z0-9_-]{0,63}, be unique, and contain no more than 32 values.

• MCP clients select a role with arguments.role. The server validates the role against the token identity and tool allow-list, then removes it before the ERP request.
• Direct callers select a role with X-ERPBridge-Role. A role in the JSON body is rejected for guarded tools.
• Open tools do not reserve role, so existing business payloads remain unchanged.
• Denied calls happen before cache lookup and downstream ERP execution.

Report authentication issues

Open an issue at github.com/nmdra/ERPBridge/issues.