Authentication

Authentication answers one question: which application is this request? Everything after — routing, restrictions, policies — hangs off the answer. It is unrelated to how the gateway reaches upstream. A registry entry’s credential is the gateway’s identity to the provider; this page is the caller’s identity to the gateway.

​

Two ways to prove it

An application is entered one of those two ways, not both: it holds a key, or it trusts one identity provider. Several applications can sit behind the same provider with different bindings, because the anchor belongs to the gateway. The Employee portal is the exception, and is not an application: people enter it with the NeuralTrust login they already have, or through your identity provider if you configured one for the platform. No key opens it.

​

Trust anchors are the gateway’s; admission is the application’s

Identity providers are trust anchors, configured once at the gateway under Machine identity and shared by any application that selects them. Trusting an IdP is not the same as admitting everyone it can vouch for, so each application narrows further with a binding: its allowed client IDs, which admit only tokens issued to those client ids. An empty list admits any client the provider verifies. The pattern this enables: one Okta tenant trusted at the gateway, and per application, the two or three client ids that may enter. The alternative — one anchor per application — multiplies configuration without adding security. Token claims decide whether a caller gets in. They never decide where it goes: registries and models come from the application’s routing, not from anything in the token.

​

Validate, or broker

The same IdP can be used two ways, and which one you want decides what you register on the IdP side. Validate a token the caller already holds. The service obtained a token from your IdP on its own — client credentials, or a user token your app acquired — and sends it. The gateway checks signature, issuer, expiry, audience and required scopes, then the application’s allowed client ids. No browser, no redirect. On the IdP this needs an issuer and an audience, nothing more. Broker the login. An MCP agent — Cursor, Claude Desktop — has no token and a person behind it. The gateway runs the sign-in itself, with authorization code and PKCE, validates what the IdP issues, and keeps that person’s upstream connections. On the IdP this needs a confidential client with the gateway’s callback registered as a redirect. A provider configured for validation only is refused for this; a person cannot sign in through something that only checks tokens.

​

Rules that bite

• Audience is required and must match the token’s aud. An api:// resource URI and its bare identifier count as the same.
• Required scopes may not include openid, profile, email or offline_access. Matching reads scp and scope, and also Entra-style roles and permissions arrays.
• Only asymmetric signatures. HMAC-signed tokens are rejected.
• A bearer that starts with ag_ is an API key. Anything else goes to the identity providers. That rule is what lets a stock SDK’s single Authorization header carry either.

​

What gets recorded

Every request records how it authenticated — api_key, external_jwt for your IdP’s token, oauth for a gateway-brokered login, introspection — and Activity shows it as Auth method. When the same application can be entered two ways, that field is how you tell which one a given request used.

​

Provider manuals