Access and authentication
Validakey has two authentication paths. Licences use the sealed token path so your private key never has to live on a customer machine.
Two paths
| Path | Endpoints | Authenticated by |
|---|---|---|
| Token | /v1/i/ /v1/r/ /v1/t/ /v1/m/ /v1/v/ /v1/p/ |
Sealed envelope under App ID or Instance ID |
| Account | /v1/u/ /v1/billing/* /v1/apps/ /v1/instance/ /v1/usage/ |
Authorization: Bearer <api_pkey> |
Only the first 8 characters of a sealing key travel in cleartext, as a lookup hint. The full User App ID or Instance ID never appears on the wire.
Identity chain
- Account UUID → create a User App ID (dashboard or account API with private key).
- User App ID + account UUID + subject + fingerprint → handshake for an Instance ID (POST /v1/i/).
- Instance ID → mint, validate, renew, revoke, rotate, and manage the customer card.
Subject is optional. When omitted, the server defaults it to the machine fingerprint — the original single-tenant behaviour. With an explicit subject, one application on one machine can serve several paying customers with separate cards and vKeys.
Why the private key stays home
The private key can change billing details and read usage for your account. Nothing on the licence path accepts it or needs it. Software you ship to end users should not carry it at all — use the dashboard for account tasks, or call account endpoints from a server you control.
Validation scope
Validating a vKey matches the calling instance’s account, application, and subject. A mismatch returns not_found, so one customer of your app cannot validate or spend another customer’s vKey.
Machine locks and transfers
You can lock an Instance Entity to its current machine from the dashboard or account API. Moving a locked instance fails with instance_locked. Transferring an Instance Entity to a different subject requires a one-shot window you authorize, then POST /v1/t/ — which rotates the Instance ID and clears the stored customer card so payment methods are not inherited.