API authentication
Use an application key for supported SDK and ingest requests. It does not grant a person’s portal or MCP permissions. Treat the complete issued value as a secret.
Compound key format
Current compound keys contain three dot-separated segments:
vp_cust_<slug>.<functions-key>.<application-key>Pass the complete key to the SDK. It separates the credential segments and sets the required headers. For direct HTTP calls, follow the endpoint contract.
Do not parse the customer slug as an authorization decision. The service resolves the authenticated customer and application from validated credentials.
Never place an application key in source control, browser code, logs, screenshots, diagnostic reports, or package-manager settings.
Store the key
Store the complete value in the approved secret manager for the application environment. Limit read access to the workload and operators who need it.
Do not use an application key as a package credential. Package downloads and runtime ingest use separate credentials.
Rotate a key
- Issue the replacement for the intended application and environment.
- Store and deploy the replacement.
- Send a representative test session.
- Confirm reporting under the intended application.
- Confirm that all intended workloads use the replacement, then revoke the previous key through the supported workflow.
Follow the application’s rotation workflow for overlap and activation behavior. A test session from one instance does not confirm that every instance has switched keys.
Use workload identity instead of a key
An application that runs on Azure can authenticate with its Microsoft Entra workload identity instead of a stored key: a managed identity, or an app registration that your platform reaches through workload identity federation (for example from GitHub Actions or AKS). There is then no application key to store or rotate.
- In the application’s key settings, add the workload identity: its Microsoft Entra tenant ID and object (principal) ID. Developers and administrators can do this for applications in their scope. Giving the identity review-continuation or verified-outcome authority needs tenant key management, as it does for a key.
- Configure the TypeScript, Python, or .NET core SDK with its workload identity credential, the application ID, and a callback that returns the workload’s Entra access token for the configured audience (Azure Resource Manager by default).
- Send a test session and check Recent token exchanges in the same settings.
- Optionally turn off Accept static keys. VeriProof then refuses this application’s keys, and only workload identity can authenticate it.
The SDK exchanges the Entra token at POST /v1/auth/sdk-workload/token for a short-lived access token (30 minutes by default) and refreshes it before it expires. The access token works only for that one application, on the same routes and with the same authority as its key. Removing the workload identity stops its tokens immediately. VeriProof records every exchange for a known application, issued or refused.
Workload identity accepts Microsoft Entra app-only tokens only. Tokens issued directly by other identity providers aren’t accepted; federate them through an Entra app registration first. An Edge Gateway checks requests against its own configured application key, so SDKs that route through an Edge Gateway keep using the key. Java, Go, and Rust SDKs use application keys.
Respond to exposure
Revoke the affected key, stop unauthorized use, and issue a replacement. Review application, ingest, and audit records for the exposure period.
Do not copy the exposed value into the incident record. Use its readable key name or identifier.
Diagnose authentication
| Result | Check |
|---|---|
401 Unauthorized | Key value, revocation status, secret injection, and endpoint |
403 Forbidden | Application scope and requested operation |
429 Too Many Requests | Response headers and the SDK retry behavior |
Read the returned error code as well as the HTTP status; the status alone does not identify the cause. Use redacted diagnostics, never credential headers.