Customer API Authentication

What authentication does

Customer API authentication lets a backend service call Wavac without a person signing in for every request. It uses the OAuth 2.0 client credentials flow for machine-to-machine access. Your service proves its own identity, receives a short-lived access token, and sends that token when it calls the Customer API.

OAuth uses the word client for the application making the request. In this documentation, client, integration, and your service all refer to that backend application. They don't refer to a browser, an individual user, or a Wavac customer account.

The OAuth roles map to Wavac as follows:

OAuth role	In this integration
Client	Your scheduled job, service, or other backend application.
Authorization server	The Wavac identity service that issues access tokens after the client proves its identity.
Resource server	The Customer API, which validates an access token before returning permitted data.

An account administrator configures what the integration may access, but no administrator or end user participates in the normal token request. This is why the flow doesn't open a browser, redirect a user, or ask for a customer password.

Understand the credentials

Platform-managed mTLS is recommended: the customer retains the certificate private key while Wavac issues 24-hour certificates and protects the internal federation signer. Customer-managed JWT assertions remain supported when the customer must own the signer. Both modes receive the same short-lived access token and remain subject to the same authorization policy.

Term	Plain-language meaning	Where it is used
Enrollment token	A one-time code that allows one CSR or public signing key to be submitted for review.	Only at the enrollment endpoint; expires after 24 hours.
mTLS key	An RSA key retained by your organization.	Signs the CSR and proves possession on token, renewal, and data requests.
Client certificate	A Wavac-issued 24-hour certificate bound to the credential.	Presented on the dedicated mTLS endpoint.
Signing key	An optional customer-managed RSA key pair.	Its public JWK is enrolled and its private key signs customer-managed assertions.
Public JWK	The public part of the signing key represented as a JSON Web Key. It can verify signatures but cannot create them.	Submitted during enrollment.
Client assertion	A JWT created and signed by your service to prove possession of the enrolled private key.	Sent only to the token endpoint; valid for no more than five minutes and accepted once.
Access token	A credential issued by the authorization server after it accepts the client assertion.	Sent as a Bearer token to Customer API routes; valid for 10 minutes.

Treat the access token as opaque. Your client can read the returned expiry and scope, but it shouldn't parse the token to make authorization decisions. The Customer API remains responsible for validating the token and current integration policy.

Follow the authentication flow

In the Wavac Dashboard, your customer administrator selects the customer, opens Settings > Customer API, creates a platform-managed integration, and selects Issue enrollment. Transfer the one-time enrollment token through an approved secure channel.
Your service sends the token to the enrollment endpoint to obtain the required certificate subject without consuming the token. It then creates an RSA mTLS key and submits the token with a CSR using that subject to complete bootstrap, while retaining the private key. Follow enrollment for the request contract.
Wavac activates the credential after validating that customer proof.
Your service presents the certificate at https://customer-api.wavac.io/api/customer/oauth/token without a customer assertion. The authorization server returns a Bearer access token valid for 10 minutes.
Your service presents that same certificate and token to HEAD /api/customer/v1/auth/session. A 204 No Content response proves the current authentication session without reading customer data or consuming the daily API allowance.
Your service sends the proven access token and certificate to a versioned Customer API route, such as /api/customer/v1/discovery.

The access token doesn't expand the integration's permissions. Current scopes, customer ownership, site and line restrictions, enabled data sources, and request limits still apply to every API request.

Keep one in-memory token manager for each integration credential. Coalesce concurrent refreshes, replace tokens before expiry with bounded jitter, and key the cache by the exact certificate and normalized scope set. The access-token guide defines the session probe and recovery pattern. The Azure discovery job contains a tested .NET implementation that can be ported without adopting its Azure storage adapters.

Rotate the authentication stack

The authentication layers have different owners and lifetimes. They rotate in a coordinated sequence, not as one customer-side secret bundle:

Layer	Owner	Safe replacement boundary
Access token	Your running service	Keep only in memory. Acquire early, prove the session, then publish to waiting callers.
mTLS key and certificate	Your organization with Wavac issuance	Generate a new key and CSR in memory. Prove token, session, and discovery access before replacing the stable vault secret.
Customer-managed assertion key	Your organization, only in customer-managed mode	Enroll a replacement public JWK, complete administrator approval, then move new assertions and token acquisition to the replacement credential.
Platform federation signer	Wavac, only in platform-managed mode	Wavac rotates HSM-backed signing keys with verification-key overlap. Customer applications neither receive nor select these keys.

For platform-managed mode, rotate the certificate first, obtain and prove a token bound to the candidate, atomically replace the stable certificate secret, and let work using the predecessor finish during its documented overlap. Never reuse a token across certificate thumbprints. Platform signer rotation is independent and must not require a customer certificate or application change.

For customer-managed mode, treat a replacement signing JWK as a new credential identity. Keep the prior credential only for the approved overlap, acquire a new token with a fresh assertion from the replacement, and remove old key access after in-flight tokens have drained. Do not overwrite an enrolled private key before the replacement has been approved and proven.

If the active private key or certificate is lost, stop normal calls and use the manual rebootstrap flow with a newly issued one-time handoff. The runner first checks whether current credentials still work, then enrolls and replaces vault state only when recovery is necessary. This keeps routine rotation automatic while making recovery an explicit customer-approved action.

Request external token federation

Microsoft Entra ID and Google token federation are available by request. Wavac must configure federation for the integration before a token from either provider can be accepted. Contact your Wavac representative for the enrollment process and the exact token requirements for your identity provider.

Federation does not make every token from that provider valid. A token issued for Microsoft Graph, Azure Key Vault, a Google API, or another audience cannot be used with the Customer API. Use only the issuer, audience, claims, and endpoint supplied for the approved integration.

Use an Azure-hosted workload

A service hosted in Azure can use Microsoft Entra ID and Azure Key Vault without changing the Wavac OAuth flow. In recommended platform-managed mode, Entra authenticates the workload to Key Vault, which stores versioned mTLS key and certificate envelopes. The workload presents the current certificate directly to Wavac and does not create a customer assertion.

Customer-managed mode can instead use a non-exportable Key Vault signing key as described in use Microsoft Entra and Azure Key Vault. Neither pattern requires external token federation. An Entra token issued for Key Vault, Microsoft Graph, or another Azure resource cannot be sent to the Customer API.

Use customer-managed assertions when required

Choose customer-managed mode when policy requires your organization to protect and operate the JWT signer. Its assertion flow is documented separately and does not weaken or bypass mTLS credentials.

Continue the setup

Start with enroll a credential, then configure platform-managed mTLS and use the access token. For customer-managed mode, request an access token with an assertion.

The protocol terminology in these articles follows the OAuth 2.0 framework (RFC 6749), Bearer token usage (RFC 6750), and JWT client assertion profile (RFC 7523).