Authentication

ApexMCP supports three authentication methods for the MCP endpoint. All methods are validated at the Gateway before the request reaches your connectors.

Method 1: Static API Key

Simplest option. No expiry, org-scoped, suitable for trusted server-side agents.

Header: X-API-Key: <key>

curl -X POST https://gateway.apexmcp.ai/mcp/acme-corp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apx_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Key management:

• Create and revoke keys in Settings → API Keys
• Keys are shown once at creation; store them in a secret manager
• Keys can be scoped to specific connectors (see Connectors)

Method 2: OAuth2 Client Credentials

Machine-to-machine flow. Returns a short-lived Bearer JWT (1-hour TTL). Recommended for production workloads.

Step 1: Get a token

curl -X POST https://gateway.apexmcp.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=apx_client_xxxxxxxx" \
  -d "client_secret=apx_secret_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d "scope=mcp:call"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp:call"
}

Step 2: Use the token

curl -X POST https://gateway.apexmcp.ai/mcp/acme-corp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Available Scopes

Create OAuth clients in Settings → OAuth Clients.

Method 3: BYOIDP (Bring Your Own Identity Provider)

Use your existing OIDC-compliant identity provider (Okta, Auth0, Azure AD, Keycloak, etc.). ApexMCP validates RS256-signed JWTs against your provider’s JWKS endpoint.

Configuration

1. Go to Settings → SSO → Configure BYOIDP
2. Enter:
   • Issuer URL — e.g. https://your-company.okta.com/oauth2/default
   • JWKS URI — e.g. https://your-company.okta.com/oauth2/default/v1/keys
   • Audience — the aud claim ApexMCP will validate (e.g. apexmcp)
3. Save — ApexMCP caches the JWKS and begins accepting tokens immediately

Making requests

Issue tokens from your IdP using the standard OAuth2 client credentials or authorization code flow, then use the resulting JWT as a Bearer token:

curl -X POST https://gateway.apexmcp.ai/mcp/acme-corp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-idp-jwt>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Requirements for the JWT:

• Algorithm: RS256
• iss must match the configured Issuer URL
• aud must match the configured Audience
• Must not be expired (exp claim)

Auth Error Responses