Gateway Authentication

Every gateway request is authenticated before any tool runs. almyty is default-deny: a gateway with no auth configured rejects all requests with 401. You add auth once, and it guards every transport (MCP, UTCP, A2A) on that gateway.

Add auth in the UI

1. Open a gateway’s detail page and click the Authentication tab
2. Click Add Auth Method
3. Select a type: API Key, Bearer Token, Basic Auth, JWT, OAuth 2.1, or None
4. Fill in the configuration and click Save

To issue API keys, click Manage Keys after adding an API Key or Bearer Token method. The raw key is shown once at creation time, then stored only as a SHA-256 hash. Keys support optional expiry, scopes, and lastUsedAt tracking.

A generated key looks like this (the key field appears only in this one response):

{
  "id": "key-uuid",
  "name": "Production Key",
  "key": "almyty_gw_abc123...",
  "scopes": ["tools:read", "tools:execute"],
  "expiresAt": "2027-01-01T00:00:00Z"
}

Authentication methods

API Key and Bearer Token

Pass the key one of three ways: an X-API-Key header, an api_key query parameter, or an Authorization: Bearer header. In an MCP client config, set it as a header:

{
  "mcpServers": {
    "petstore": {
      "url": "https://api.almyty.com/acme/petstore",
      "headers": { "x-api-key": "almyty_gw_abc123..." }
    }
  }
}

Basic Auth

Decodes the Authorization: Basic header, looks up the user by email, and verifies the password with bcrypt.

JWT

Verifies the JWT signature using the secret configured on the auth method (or the server’s JWT_SECRET as a fallback). The payload must contain sub or userId.

Enforcement pipeline

Every request to a gateway endpoint passes through the same pipeline:

1. Resolve the organization and gateway from the URL
2. Load all active auth configs for that gateway
3. If no auth configs exist, reject with 401
4. Try each required auth method in order: first success wins
5. If all fail, reject with the last error (401 or 403)
6. If valid, execute the request

Discovery endpoints (.well-known/*, Agent Cards) are always public.

OAuth 2.1 (MCP OAuth)

almyty implements a full OAuth 2.1 authorization server per the MCP specification:

• Authorization Code flow with PKCE (S256 mandatory)
• Dynamic Client Registration (RFC 7591)
• Token Revocation (RFC 7009)
• Authorization Server Metadata (RFC 8414)
• Protected Resource Metadata (RFC 9728)

MCP clients handle this flow for you. On a 401, the gateway returns a WWW-Authenticate header pointing at the protected resource metadata, and a compatible client registers itself, runs the authorization code exchange, and attaches the token automatically.

Discovery endpoints

https://api.almyty.com/acme/petstore/.well-known/oauth-authorization-server
https://api.almyty.com/acme/petstore/.well-known/oauth-protected-resource

Flow endpoints

Token lifetimes

Refresh tokens rotate on use. Revoking a refresh token also revokes its access tokens.

Validation rules

Auth methods can carry extra validation. Restrict by IP range:

{
  "validationRules": {
    "allowedIpRanges": ["10.0.0.0/8", "192.168.1.100"]
  }
}

Or require specific headers:

{
  "validationRules": {
    "requiredHeaders": ["X-Request-Id", "X-Client-Version"]
  }
}

Key scopes

Multiple auth methods

A gateway can carry several auth methods, each marked required or optional. Required methods are tried in order (first match wins), so you can combine them for a gradual migration, for example adding OAuth while keeping API keys active.