Download the PHP package validakey/validakey-php without Composer

Validakey PHP Client

Framework-agnostic PHP client for the Validakey v1 API.

Install via Composer:

Documentation

Full usage guides are in the docs/ folder:

• Getting started
• Configuration
• Access and authentication
• API reference
• Error handling
• WordPress plugin integration — LicenseBootstrap::register(), allows(), admin panel, cron

Requirements

• PHP 8.1+
• Symfony HttpClient (installed automatically)

Configuration

Never commit secrets. Pass credentials from your application environment or plugin settings:

Or load from environment variables:

Copy .env.example to .env locally for development (do not commit .env). See Configuration for details.

apiPKey is your account private key, and most applications should leave it out. Only the account endpoints — user info and the account holder's own billing — read it. Everything to do with licenses (minting, validating, renewing, revoking, and collecting your customer's card) is authenticated by the instance handshake instead.

Do not ship the private key in software you distribute, and do not commit it. It can change billing details and read usage for the whole account, and no license operation needs it.

Instances

Token requests are not authenticated by a shared secret in the request. On first use the client performs a handshake, sealed with your userAppId, and the server grants an instance id scoped to this application, this subject, and this machine. That instance id keys every later token request, and neither it nor your account UUID travels in cleartext.

Give the client somewhere to keep the instance id, or it will handshake once per PHP process:

A repeat handshake rotates the instance and invalidates the previous one, so a persistent store matters for more than performance. See Access and authentication for the protocol and its trade-offs.

To rotate deliberately, use rotateInstance() rather than a repeat handshake. It is sealed under the id being replaced, so only a holder of the live instance id can rotate it, and the server does not treat it as a possible cloned application:

For multi-tenant applications, fork the client per end-customer subject:

If you omit subject, the client assigns a random Subject ID and persists it in the instance store. The handshake requires a subject; the library supplies one so a single-tenant app does not have to.

Usage

See API reference for complete examples. Quick start:

Create a token

Validate, renew and revoke

Validation is read-only. Pass consume: true to spend one use of a use-limited vKey — a license check on startup and an actual use are different events, and only the second should draw down an allowance:

Renewing adds time or uses without changing the vKey value, so copies already deployed keep working. Revoking is what ends a vKey that has no expiry:

Validation is never refused because the account's own billing lapsed. A customer who paid for a license keeps it.

Collect your customer's card

The customer running your software — their Instance Entity — pays for their own vKeys, on their own card, stored against their instance. Card numbers go from their browser to Square directly; neither this library nor the Validakey server ever sees one.

If your application has a web frontend, collect a source_id there with Square's Web Payments SDK and seal it:

For a CLI or desktop application with no browser to host that form in, ask for a link and print it:

The link is single-use, expires in fifteen minutes, and can do nothing but attach a card to that one instance.

Minting a vKey that carries a price fails with ie_card_required (HTTP 402) when the customer has no card on file, so you can prompt rather than guess. Your own card is deliberately not a fallback.

Your account (private key)

These act on your account rather than your customer's, and are the only calls that read the private key. Keep them out of anything you distribute.

Your card covers the monthly service fee and the per-event platform fee:

Error handling

API routes

Only the private-key routes carry cleartext identity headers (X-Validakey-User-App-Id, X-Validakey-User-Id, X-Validakey-Host). The sealed routes send a single encrypted field and nothing else.

Development