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
}

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.