Standards & Conformance

Apiway is an OAuth 2.0 authorisation server and an OpenID Connect provider. Nothing here is proprietary: if your client library speaks the standards, it works, and if your security team reviews against them, this is the surface to review.

Endpoints

Each API exposes its own authorisation surface, so the paths below are relative to the API’s base route.

Endpoint	Path	Purpose
Discovery	/.well-known/openid-configuration	OIDC discovery document. Start here; everything else can be resolved from it.
JWKS	/.well-known/jwks	Signing keys for token verification.
Protected resource metadata	/.well-known/oauth-protected-resource	RFC 9728. How an MCP client or other resource consumer discovers which authorisation server protects this API.
Authorize	/oauth2/v2/authorize	Authorization code flow.
Token	/oauth2/v2/token	Token issuance for all supported grants.
Device authorization	/oauth2/v2/device_authorization	RFC 8628, for input-constrained clients.
Introspect	/oauth2/v2/introspect	RFC 7662 token introspection.
Revoke	/oauth2/v2/revoke	RFC 7009 token revocation.
UserInfo	/oauth2/v2/userinfo	OIDC claims for an authenticated subject.

Note

Tokens are minted at a specific API’s token endpoint. There is no product-level token endpoint — a product is a way of grouping and subscribing to APIs, not a separate audience. Subscribing to a product gives you one credential; you present it at each member API’s token endpoint for a token scoped to that API.

Grants

Grant	Use
Client credentials	Machine-to-machine: services, partner systems, AI agents
Authorization code with PKCE	User-facing applications. RFC 7636.
Device authorization	Command-line tools and devices without a browser

Tokens

Access tokens are JWTs, signed with a key published at the JWKS endpoint, and carry expires_in of 3600 seconds by default.

They are verified on every request — signature against the current key set, issuer, audience and expiry — and the caller’s current entitlements are resolved at that moment rather than trusted from the token. Revoking access therefore takes effect on the next request rather than at expiry. See Security.

Key rotation requires no coordination: clients resolve keys from the JWKS endpoint, so a rotated key is picked up without redeployment or configuration on your side.

Error Behaviour

Conformant with RFC 6750, and worth knowing because the distinction is often collapsed:

Condition	Response
No credential presented	401 with a WWW-Authenticate challenge
Credential invalid, expired, or signature fails	401
Credential valid, but lacks the scope for this operation	403 with insufficient_scope
Over rate limit	429

A 403 means the credential verified and the caller simply is not entitled to that operation — which is a different problem from a 401 and should be handled differently by a client. Scopes are enforced per operation rather than per API, so entitlement to read an API does not imply entitlement to write to it.

Federating Your Own Provider

Any OIDC-compliant provider federates — Microsoft Entra ID, Okta, Google Workspace, Keycloak, or a consumer identity product for a customer-facing portal. The configuration is client credentials and a discovery URL. See Identity Providers.

Specifications

OAuth 2.0 (RFC 6749) · Bearer tokens (RFC 6750) · PKCE (RFC 7636) · Token revocation (RFC 7009) · Token introspection (RFC 7662) · Device authorization grant (RFC 8628) · Protected resource metadata (RFC 9728) · JSON Web Token (RFC 7519) · JSON Web Key (RFC 7517) · OpenID Connect Core and Discovery · OpenAPI 3.x

See also: Security · Authentication · Scopes & Entitlements · Identity Providers