Skip to main content

Environment setup

AuthSec SDKs read their config from a single set of environment variables. This page shows how to load them in .env, bash/zsh, PowerShell, Windows Command Prompt, Docker, and Kubernetes — all four shell flavors the dashboard's Protect step also emits.

The variables​

The same keys are used by Go, Python, and TypeScript SDKs:

VariablePurpose
AUTHSEC_RESOURCE_SERVER_IDYour resource server's UUID.
AUTHSEC_RESOURCE_URIThe canonical URI for this protected resource.
AUTHSEC_RESOURCE_NAMEHuman-readable name (for logs and metadata).
AUTHSEC_ISSUEROAuth issuer (AuthSec).
AUTHSEC_AUTHORIZATION_SERVERAuthSec API origin used for non-issuer paths.
AUTHSEC_JWKS_URLJWKS endpoint for verifying user tokens.
AUTHSEC_INTROSPECTION_URLToken introspection endpoint.
AUTHSEC_INTROSPECTION_CLIENT_IDSame value as AUTHSEC_RESOURCE_SERVER_ID.
AUTHSEC_INTROSPECTION_CLIENT_SECRETThe one-time secret AuthSec shows you at creation / rotation time.
AUTHSEC_INTROSPECTION_SECRETLegacy alias for AUTHSEC_INTROSPECTION_CLIENT_SECRET; set both.
AUTHSEC_POLICY_MODEremote_required in production.
AUTHSEC_PUBLISH_MANIFESTtrue to publish your tool manifest to AuthSec on start.

In addition, your MCP server keeps an upstream service credential — e.g. AUTHSEC_UPSTREAM_GITHUB_TOKEN for the GitHub MCP server, or UPSTREAM_API_TOKEN generically. This is not an AuthSec value; it is the credential your server uses to talk to its provider, server-side only.

Pick your shell​

The Protect step in the dashboard emits one of these four flavors. Pick the one that matches your deployment target.

.env file​

Drop this into a .env next to your service (or into the secret manager your platform reads at boot).

AUTHSEC_RESOURCE_SERVER_ID=<your-resource-server-id>
AUTHSEC_RESOURCE_URI=https://example.com/mcp
AUTHSEC_RESOURCE_NAME=<your-resource-name>
AUTHSEC_ISSUER=https://dev.api.authsec.dev
AUTHSEC_AUTHORIZATION_SERVER=https://dev.api.authsec.dev
AUTHSEC_JWKS_URL=https://dev.api.authsec.dev/oauth/jwks
AUTHSEC_INTROSPECTION_URL=https://dev.api.authsec.dev/oauth/introspect
AUTHSEC_INTROSPECTION_CLIENT_ID=<your-resource-server-id>
AUTHSEC_INTROSPECTION_CLIENT_SECRET=<one-time-secret>
AUTHSEC_INTROSPECTION_SECRET=<one-time-secret>
AUTHSEC_POLICY_MODE=remote_required
AUTHSEC_PUBLISH_MANIFEST=true

macOS / Linux (bash · zsh)​

Paste into your shell to export them into the current session, or add to your service's systemd unit.

export AUTHSEC_RESOURCE_SERVER_ID=<your-resource-server-id>
export AUTHSEC_RESOURCE_URI=https://example.com/mcp
export AUTHSEC_ISSUER=https://dev.api.authsec.dev
export AUTHSEC_JWKS_URL=https://dev.api.authsec.dev/oauth/jwks
export AUTHSEC_INTROSPECTION_URL=https://dev.api.authsec.dev/oauth/introspect
export AUTHSEC_INTROSPECTION_CLIENT_ID=<your-resource-server-id>
export AUTHSEC_INTROSPECTION_CLIENT_SECRET=<one-time-secret>
export AUTHSEC_POLICY_MODE=remote_required
export AUTHSEC_PUBLISH_MANIFEST=true

Windows PowerShell​

$Env:AUTHSEC_RESOURCE_SERVER_ID = "<your-resource-server-id>"
$Env:AUTHSEC_RESOURCE_URI = "https://example.com/mcp"
$Env:AUTHSEC_ISSUER = "https://dev.api.authsec.dev"
$Env:AUTHSEC_JWKS_URL = "https://dev.api.authsec.dev/oauth/jwks"
$Env:AUTHSEC_INTROSPECTION_URL = "https://dev.api.authsec.dev/oauth/introspect"
$Env:AUTHSEC_INTROSPECTION_CLIENT_ID = "<your-resource-server-id>"
$Env:AUTHSEC_INTROSPECTION_CLIENT_SECRET = "<one-time-secret>"
$Env:AUTHSEC_POLICY_MODE = "remote_required"
$Env:AUTHSEC_PUBLISH_MANIFEST = "true"

Windows Command Prompt​

set AUTHSEC_RESOURCE_SERVER_ID=<your-resource-server-id>
set AUTHSEC_RESOURCE_URI=https://example.com/mcp
set AUTHSEC_ISSUER=https://dev.api.authsec.dev
set AUTHSEC_JWKS_URL=https://dev.api.authsec.dev/oauth/jwks
set AUTHSEC_INTROSPECTION_URL=https://dev.api.authsec.dev/oauth/introspect
set AUTHSEC_INTROSPECTION_CLIENT_ID=<your-resource-server-id>
set AUTHSEC_INTROSPECTION_CLIENT_SECRET=<one-time-secret>
set AUTHSEC_POLICY_MODE=remote_required
set AUTHSEC_PUBLISH_MANIFEST=true

Docker​

Pass with -e or via an --env-file:

docker run \
  -e AUTHSEC_RESOURCE_SERVER_ID=<your-resource-server-id> \
  -e AUTHSEC_RESOURCE_URI=https://example.com/mcp \
  -e AUTHSEC_ISSUER=https://dev.api.authsec.dev \
  -e AUTHSEC_INTROSPECTION_URL=https://dev.api.authsec.dev/oauth/introspect \
  -e AUTHSEC_INTROSPECTION_CLIENT_ID=<your-resource-server-id> \
  -e AUTHSEC_INTROSPECTION_CLIENT_SECRET=<one-time-secret> \
  -e AUTHSEC_POLICY_MODE=remote_required \
  -e AUTHSEC_PUBLISH_MANIFEST=true \
  your-mcp-image

Kubernetes Secret​

Store the introspection secret in a Kubernetes Secret and mount the rest through a ConfigMap or Deployment env block:

apiVersion: v1
kind: Secret
metadata:
  name: authsec-introspection
type: Opaque
stringData:
  client-secret: "<one-time-secret>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: your-mcp
spec:
  template:
    spec:
      containers:
        - name: mcp
          env:
            - name: AUTHSEC_RESOURCE_SERVER_ID
              value: "<your-resource-server-id>"
            - name: AUTHSEC_RESOURCE_URI
              value: "https://example.com/mcp"
            - name: AUTHSEC_ISSUER
              value: "https://dev.api.authsec.dev"
            - name: AUTHSEC_INTROSPECTION_URL
              value: "https://dev.api.authsec.dev/oauth/introspect"
            - name: AUTHSEC_INTROSPECTION_CLIENT_ID
              value: "<your-resource-server-id>"
            - name: AUTHSEC_INTROSPECTION_CLIENT_SECRET
              valueFrom:
                secretKeyRef:
                  name: authsec-introspection
                  key: client-secret
            - name: AUTHSEC_POLICY_MODE
              value: "remote_required"
            - name: AUTHSEC_PUBLISH_MANIFEST
              value: "true"

Verify​

Once your MCP server is started with these values, run Run protection check in the dashboard's Step 4. The bearer-challenge check should pass immediately, and the SDK-manifest check passes after AuthSec receives a tools/list from your SDK on startup.

See also​