Authorization servers

An authorization server is an upstream OAuth issuer that the platform trusts, such as the one behind a SaaS API like Linear, or a company identity provider. It issues the per-user OAuth tokens that let an MCP server act for each user in the upstream service. MCP servers also use it to authenticate clients before they reach a server. OpenID Connect (OIDC) identity is optional; a plain OAuth authorization server is enough. Setting up the authorization server once lets every MCP server that talks to that issuer share the same client and sign-in flow. Open the Authorization Servers page from Identity > Authorization Servers in the project sidebar.

Access requirements

Viewing authorization servers requires the org:read scope, which both default roles hold. Creating, editing, moving, consolidating, and deleting authorization servers, and managing their clients, requires org:admin, which only the Admin role includes by default. Registering a client by dynamic client registration through a tunnel-bound authorization server requires a Speakeasy platform administrator. A service account client can also be created from an MCP server’s Identity section with project:write and mcp:write, as described in Upstream credentials.

Where an authorization server lives

Authorization servers exist at three levels:

• Platform authorization servers are maintained by Speakeasy for common issuers. Organizations cannot edit them, but they can add clients to them.
• Organizational authorization servers are shared by every project in the organization.
• Project-specific authorization servers apply to one project.

Prefer a platform authorization server when one exists for the issuer. Create an organizational or project-specific authorization server only when the organization needs its own setup documentation, branding, scopes, or audience handling.

Trust an upstream issuer

Select New Authorization Server, choose whether the authorization server is organizational or belongs to one project, and enter the Issuer URL. Discover reads the issuer’s published metadata (RFC 8414) and fills in the authorization, token, registration, and JWKS endpoints. Endpoints the issuer does not publish can be entered by hand. Add a display name, logo, and a Client setup documentation URL so admins know how to create a client with this issuer.

If an entry for the same upstream authorization server already exists at any level, the form warns and links to it. The warning does not block saving. Discovery also warns when the issuer does not advertise PKCE S256.

When the issuer changes its metadata, use Refresh Discoverable Metadata to update the stored endpoints.

Register a client

An authorization server needs a registered OAuth client before MCP servers can use it. Select Add Client, or New Client on the authorization server’s Clients tab.

Signs in as decides whose upstream credential the client holds, and is fixed once the client is created:

• Each user: every caller connects their own account at the authorization server. This is the client a server uses for User Identity.
• Service account: the client gets one token for itself with the OAuth client credentials grant, and every caller shares it. See Service account clients.

An Each user client can be registered three ways:

• Dynamic Client Registration (DCR) registers a client automatically when the issuer has a registration endpoint (RFC 7591). Rotate client later registers a replacement and swaps it in place, which signs out existing sessions so users reconnect once.
• Client ID Metadata Document (CIMD) uses a public document the platform hosts as the client ID, when the issuer supports it. No credentials are stored, so there is nothing to expire or rotate.
• Manual uses a client registered with the issuer outside the platform. Paste its client ID and secret. The sheet shows the callback URI to register with the issuer.

MCP servers select an authorization server in their authentication settings. An MCP server holds at most one authorization server. A gateway can hold one per member server. See Upstream credentials for how a server uses an authorization server and what users see when they connect.

Deleting a client revokes every session issued through it. Client secrets are encrypted at rest and never displayed.

Service account clients

A service account client holds one upstream credential for itself instead of one per person. The platform requests its access token from the authorization server’s token endpoint with the OAuth client credentials grant, and an MCP server that uses it sends that token upstream for every caller. See OAuth client credentials on remote servers for how a server uses one.

The quickest way to create one is from the MCP server’s Identity section, which creates the client and attaches it to the server in one step. To create one from the authorization server instead, choose Service account under Signs in as in the New Client sheet:

1. Create a machine-to-machine app at the authorization server that is allowed the client credentials grant, and turn off DPoP for it, since the platform does not send DPoP proofs.
2. Paste the app’s Client ID.
3. Choose the Token Endpoint Auth Method: a secret in the Authorization header (client_secret_basic, the default), a secret in the request body (client_secret_post), or an assertion signed with one of the organization’s key sets (private_key_jwt). Enter the Client Secret, or pick the key set and the Client assertion audience. private_key_jwt shows Requires KMS without the customer-managed encryption keys entitlement.
4. Optionally set Scope (override), comma-separated, and Audience (optional). A service account client requests no scopes when the override is empty. On an organizational authorization server, also choose whether the client serves all projects or one.
5. Select Create.

Selecting Create opens the client’s page. For a private_key_jwt client, that page shows the Key set URL and Public key to register with the authorization server.

The authorization server must have a token endpoint. When it publishes none, Service account is disabled until one is added on the authorization server’s Settings tab. The endpoint can be entered by hand without metadata discovery, and it cannot be removed while a service account client depends on it.

A service account client is marked Service account on the authorization server’s Clients tab and on its own page, where Signs in as reads Itself. Its token endpoint auth method can be changed later, except to none, since a service account client must always authenticate. It cannot be rotated by dynamic client registration or used for trusted identity provider login. When the authorization server stops accepting its credentials, MCP servers that use it report an upstream credential error to callers until a new secret or key is entered. Deleting a service account client is allowed while MCP servers use it, and those servers then stop authenticating upstream.

Authenticate a client with a signed key

A client can authenticate to the issuer with a signed assertion instead of a shared secret. Set the client’s token endpoint authentication method to private_key_jwt and attach a Signing key set. The assertion audience defaults to the issuer identifier and can be switched to the token endpoint URL for issuers that require it. A key set cannot be deleted while a client uses it.

For a service account client, the client’s page also shows the Key set URL and the Public key to register with the authorization server, so it can verify the client’s assertions.

Signing key sets are created from the organization’s own KMS keys on Encryption Keys and require the customer-managed encryption keys entitlement.

Reach a private issuer through a tunnel

When an issuer is reachable only from a private network, bind the authorization server to an MCP tunnel in the project with the OAuth network route setting. All traffic between the platform and the issuer then goes through the tunnel, including discovery, token exchange and refresh, revocation, and client registration. Choose a tunnel whose target can reach the issuer. If the tunnel is deleted, OAuth for that authorization server fails until an admin changes the route. See Tunneled MCP servers to set up the tunnel.

Move, merge, or delete an authorization server

• Make organizational shares a project-specific authorization server with every project. Make project-specific and Move to another project scope it to one project.
• Consolidate into another authorization server moves this authorization server’s clients onto another one for the same issuer. It is refused when the two point at different endpoints, because existing sessions would break, or when both already have a client on the same MCP server.
• Delete is blocked while clients are still registered, and names the affected MCP servers.

An authorization server’s display name and logo appear on the MCP consent page and wherever the dashboard names it.