Authentication

Apiway supports multiple authentication methods. The gateway enforces authentication at the operation level — each operation can have its own security requirements.

OAuth 2.0 Client Credentials

The most common flow for API-to-API communication. The consumer authenticates with a client ID and secret, and receives a JWT.

The flow:

1. Consumer app sends client_id + client_secret to the gateway’s token endpoint
2. Gateway returns a JWT with the consumer’s entitled scopes
3. Consumer calls API operations with Authorization: Bearer {jwt}
4. Gateway verifies the JWT and checks scopes per operation
5. Request is forwarded to the backend

Getting Credentials

When a subscription is created, Apiway provisions credentials automatically.

Platform API

curl https://core.api.apiway.net/v1/subscriptions/{id}/credentials \
  -H "Authorization: Bearer $TOKEN"

Management UI

Navigate to the subscription details page. Credentials are shown with a copy button. Client secrets are shown once — store them securely.

Token Request

curl -X POST https://alpha.gateway.apiway.net/{api}/oauth2/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={id}&client_secret={secret}"

Response:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Scope Negotiation

Per RFC 6749 §3.3, the gateway issues a token whose scope is the intersection of what the client requested, what the credential is granted, and what the target API’s OAS declares. Pass scope=read:design write:design on the token request to narrow the token to only those operations; the gateway drops anything the API doesn’t declare.

Product Credentials

A Product subscription provisions one shared credential authorised across every member API in the bundle (see Subscribing). There is no product-level token endpoint — tokens are always minted at a specific member API’s /{api}/oauth2/v2/token endpoint using the shared credential.

To call multiple member APIs, the client mints one token per API:

# Subscribed to product apiway-platform → shared credential (clientId, clientSecret).
# Want to call design-api:
curl -X POST https://alpha.gateway.apiway.net/design-api/v1/oauth2/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={shared-id}&client_secret={shared-secret}&scope=read:design"

# Want to also call recommendations-api → mint a separate token at its endpoint:
curl -X POST https://alpha.gateway.apiway.net/recommendations-api/v1/oauth2/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={shared-id}&client_secret={shared-secret}&scope=read:recommendations"

Each issued token’s aud claim pins to one member API. The gateway validates per-API at request time: (credential.ApiProductId ∈ proxy.MemberOfProductIds) AND (token.scopes ⊆ proxy.allowed).

This pattern keeps Authorization headers below the upstream proxy header limit (no scope-union explosion across large bundles), preserves OAuth2’s intersection contract, and prevents scope leakage across member APIs.

OAuth 2.0 Authorization Code

For user-facing applications where a human grants access. Supports standard redirect-based flow and PKCE for public clients.

PKCE Flow

Best for single-page apps and mobile apps that can’t securely store a client secret.

# 1. Generate code verifier and challenge
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=+/' | head -c 43)
CODE_CHALLENGE=$(echo -n $CODE_VERIFIER | openssl dgst -sha256 -binary | base64 | tr -d '=+/')

# 2. Redirect user to authorize endpoint
# GET /oauth2/v2/authorize?response_type=code&client_id={id}
#     &code_challenge={challenge}&code_challenge_method=S256

# 3. Exchange code for token
curl -X POST https://alpha.gateway.apiway.net/{api}/oauth2/v2/token \
  -d "grant_type=authorization_code&code={code}&code_verifier={verifier}&client_id={id}"

API Keys

For simpler integrations where OAuth overhead isn’t justified.

curl https://alpha.gateway.apiway.net/{api}/resources \
  -H "x-api-key: {your-api-key}"

API keys are provisioned per subscription, scoped to entitled operations, and rate-limited like OAuth-authenticated requests.

Prefer OAuth for production

API keys are simpler but less secure — they can’t be scoped to specific grant types, don’t expire automatically, and are harder to rotate. Use OAuth 2.0 client credentials for production workloads.

Signing Algorithms

The gateway supports two JWT signing algorithms:

Algorithm	Type	Performance
ES256	ECDSA P-256	Preferred — faster, shorter signatures
RS256	RSA	Supported for compatibility

ES256 is used by default when available. JWKS keys are published at the /.well-known/jwks endpoint for token verification.

External Identity Providers

Apiway can integrate with external IdPs (e.g., Clerk, Azure AD B2C) for user authentication. The gateway validates tokens issued by the external IdP using the standard open-id-jwt-auth-inbound policy.

Configure IdP associations per environment through the Operations Service.