OAuth2

How Permix uses OAuth2 client credentials — for the Java SDK startup registration and for issuing service API keys to machine callers.

Edit this page on GitHub

Permix integrates with OAuth2 in two ways: the Java SDK uses the client_credentials flow to register resources at startup, and your services can authenticate to the authorization API using service API keys as a lightweight alternative to OAuth2 for internal calls.

Client credentials in the Java SDK#

When a Spring Boot or Quarkus service starts up, authorization-core exchanges a client_credentials grant to obtain an admin token, then POSTs all discovered @Resource-annotated methods to POST /resources/list.

Token exchange request:

http

POST {AUTH_SERVER_URL}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=iotlab-admin
&client_secret=your-secret

Configuration:

env

# Java SDK environment variables
ADMIN_CLIENT_ID=iotlab-admin
ADMIN_CLIENT_SECRET=your-secret

properties

# Spring Boot — OIDC server URL for token exchange
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://keycloak.example.com/realms/myrealm

# Quarkus — OIDC server URL for token exchange
quarkus.oidc.auth-server-url=https://keycloak.example.com/realms/myrealm

The token URL is constructed as {AUTH_SERVER_URL}/protocol/openid-connect/token. The SDK logs a WARN and skips registration if any of tokenUrl, clientId, or clientSecret is missing.

Service API keys as an alternative#

For microservices that call the authorization API directly without a user JWT, service API keys are a simpler and more portable option than client credentials — no token endpoint, no expiry refresh, no OIDC dependency.

Create a key once:

bash

curl -X POST https://api.permix.dev/api/v1/service-api-keys \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -d '{ "name": "my-worker" }'

Then use it on every call:

http

X-Service-Api-Key: sak_live_xxxxxxxxxxxxxxxx

See Authentication for the full service API key lifecycle.

Runtime JWT validation#

Inbound JWTs from your identity provider are validated on every authenticated request. The service fetches the JWKS endpoint at startup and caches validators per issuer. No OAuth2 introspection endpoint is required — the service validates tokens locally using the public keys from the JWKS.

Supported grant flows in your IdP:

Flow	Use case
`authorization_code`	User-facing applications — issues short-lived JWTs
`client_credentials`	Machine-to-machine — background services, the Java SDK startup
`refresh_token`	Renewing user sessions without re-authentication

All flows produce a JWT that Permix validates in the same way. The grant type does not affect how the token is evaluated against RBAC/ABAC policies.

Multi-tenant OIDC#

In SaaS mode, each tenant registers its own identity provider with its own JWKS endpoint. The ValidatorCache resolves the correct JWKS by matching the iss claim in the incoming JWT. Multiple tenants can use different IdPs (Keycloak, Auth0, Okta) simultaneously without any shared configuration.

See Identity Providers for IdP registration and claim configuration.