Authenticate to the gateway

Before you can register servers, author policy, or call tools, the gateway has to know who you are. This page assumes a gateway is already deployed and reachable at $GATEWAY.

Authentication modes

Your gateway is configured for one of four modes (set by whoever deployed it). How you get a token depends on the mode:

Mode	When it’s used	How you authenticate
oidc_jwt	Production with an identity provider	Send a Bearer JWT from your IdP in Authorization.
trusted_proxy	Behind a reverse proxy that authenticates users	The proxy injects normalized x-gateway-* identity headers.
local_identity	Self‑hosted without an external IdP	Username/password login; the first admin is bootstrapped once.
local_header_bootstrap	Dev / evaluation only	Trusted identity headers; never for production.

Caution

local_header_bootstrap trusts client-supplied identity headers and is intended for local development only. Don’t expose a gateway in this mode to a network you don’t control.

For the most common production case (oidc_jwt), obtain an access token from your identity provider and export it:

export GATEWAY="https://your-gateway.example.com"
export TOKEN="<JWT from your IdP>"

For local_identity, the operator bootstraps the first admin with the CLI, then you log in:

gatewayctl bootstrap-admin --email you@example.com

Verify your access

Confirm the gateway recognizes you and see exactly which permissions you hold. This is the fastest way to tell whether a later 403 is an auth problem or a policy one.

Confirm your identity and permissions

UIAPICLI

1. Sign in to the console.
2. Open the account menu in the top bar — your actor, roles, tenant, and environment are listed there.

GET/v1/identity/me

Copy

curl "$GATEWAY/v1/identity/me" \
-H "authorization: Bearer $TOKEN"

View getIdentityMe in the API reference →

Copy

gatewayctl status deployment --format json

There is no dedicated identity verb yet — use the API GET /v1/identity/me, or check deployment scope with gatewayctl status.

If this returns your actor with the roles you expect, you’re ready for your first governed tool call.

Permissions, not just identity

MCP Gateway uses fine-grained, colon-style permissions granted through role bindings (for example mcp_server.register, policy.publish, audit.read). The response above lists the permissions computed for you — if an action 403s, check this first.