Authentication

The ERPBridge SDK supports consume-only bearer authentication for ERPBridge v0.3.0-alpha.1 and later. An ERPBridge administrator provisions the opaque token. The ERPBridge SDK sends the token but never creates, lists, reveals, revokes, refreshes, or stores tokens.

Configuration

Set an explicit token or an environment-variable name. The ERPBridge SDK resolves the credential once when createClient runs:

import { createClient } from '@erpbridge/sdk'

const client = createClient({
  baseUrl: 'https://bridge.example.com',
  tokenEnv: 'ERPBRIDGE_TOKEN',
  auth: {
    metrics: { tokenEnv: 'ERPBRIDGE_METRICS_TOKEN' },
    logs: { tokenEnv: 'ERPBRIDGE_LOGS_TOKEN' },
  },
})

The default environment variable is ERPBRIDGE_TOKEN. The legacy ERPBridge_TOKEN name is checked only when the canonical variable is absent, so existing deployments continue to work while they migrate.

For each MCP, metrics, or logs request, the ERPBridge SDK uses this precedence:

1. surface token;
2. surface tokenEnv value;
3. global token;
4. global tokenEnv value, defaulting to ERPBRIDGE_TOKEN, then the legacy ERPBridge_TOKEN value when the canonical variable is absent;
5. anonymous access.

The ERPBridge SDK treats an empty token as absent. A browser bundle cannot read a Node environment automatically. Provide a token explicitly when the server requires authentication. Do not put a long-lived token in a public browser bundle unless the deployment design makes that safe.

The ERPBridge SDK also uses the global credential for health, cache, registry, and direct invoke requests. It does not locally assert that this credential has the server's admin permission.

Server scopes

When server authentication is enabled, the protected surface scopes are:

SDK surface	Server scope
client.mcp and client.tools	mcp
client.metrics	metrics
client.logs	logs

Declare expected scopes for local fail-fast checks:

const client = createClient({
  tokenEnv: 'ERPBRIDGE_TOKEN',
  declaredScopes: ['mcp'],
})

declaredScopes is an application assertion, not token introspection. If you omit it, the ERPBridge SDK sends the request and lets the server decide. It never infers permissions from an opaque token.

If a non-empty declaration excludes the requested surface, the ERPBridge SDK throws AuthorizationError before it makes a network request. This local check only detects configuration errors. The server remains the authority.

Errors

• AuthenticationError represents HTTP 401: the server did not accept the credential. Its optional wwwAuthenticate field is the server challenge; Applications must not log its value.
• AuthorizationError represents HTTP 403: the credential is not authorized for the request. Its optional requiredScope is present only when the server explicitly supplies one.

The ERPBridge SDK does not implement OAuth, PKCE, token refresh, or token lifecycle operations. Use bridgectl or the server administrator workflow to manage tokens.