Authentication

Every call to the Developer License API is authenticated with a vendor API key. This is a server-to-server credential that identifies you as the vendor and authorizes calls on behalf of every license you have sold. It is not tied to any single buyer, and it is not the OAuth flow your customers use to sign in to their Code Heaven dashboard.

The X-CH-Vendor-Key header

Send your key in the X-CH-Vendor-Key request header on every request. In OpenAPI terms this is an apiKey security scheme located in the header.

POST /v1/licenses/validate HTTP/1.1
Host: api.code-heaven.com
Content-Type: application/json
X-CH-Vendor-Key: ch_vendor_live_8f3c2a91d4e7b605...

With curl:

curl https://api.code-heaven.com/v1/licenses/validate \
  -H "X-CH-Vendor-Key: $CH_VENDOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"licenseKey":"CH-7K2P-9XQ4-LM83","domain":"example.com"}'

There is no Authorization: Bearer header, no token exchange, and no refresh step. The key is the credential. Keep it secret.

How to obtain a key

1. Sign in to your Code Heaven vendor dashboard.
2. Open Settings → API Keys.
3. Click Generate vendor key. Code Heaven shows the full key once. Copy it immediately and store it in your secrets manager — it is not retrievable later.
4. To rotate, generate a new key and delete the old one. Both keys work during the overlap window so you can deploy the new key without downtime.

Keys are prefixed so you can tell them apart at a glance:

Prefix	Environment
ch_vendor_live_	Production — operates on real licenses
ch_vendor_test_	Sandbox — operates on test licenses only, no billing effect

Develop and run your integration tests against a test key. Switch to the live key only in production.

Missing or invalid keys

If the header is absent, malformed, or revoked, the API responds 401 and rejects the request before doing any work.

{
  "error": {
    "code": "missing_vendor_key",
    "message": "No X-CH-Vendor-Key header was provided."
  }
}

{
  "error": {
    "code": "invalid_vendor_key",
    "message": "The provided vendor key is invalid or has been revoked."
  }
}

A 401 is an authentication failure — it means the caller is not trusted. Do not confuse it with 403 (license_invalid, expired, domain_not_activated), which means the caller is trusted but the license in the request is not entitled. See the license lifecycle for the full status list.

Rate limits

Requests are rate limited per vendor key. When you exceed the limit, the API responds 429:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the window resets."
  }
}

Honour the Retry-After response header and back off. Practical guidance:

• Validate sparingly. Do not call /licenses/validate on every page load. Validate once when the key is entered, then again on a daily schedule, and cache the result in between. The PHP SDK does this caching for you.
• Poll updates daily, not hourly. A WordPress update check that fires once a day is more than enough.
• Use exponential backoff with jitter on 429 and on 5xx. Retry the request after the delay; never hammer the endpoint in a tight loop.
• Batch installs gracefully. If you are migrating many sites at once, stagger the activation calls.

Never expose the key client-side

The vendor key authorizes calls for every license you have sold. If it leaks, anyone can read and mutate your customers' license records. Treat it like a database password.

Do not put the vendor key in:

• JavaScript bundles, browser code, or any front-end asset shipped to the visitor.
• The WordPress options table in a way that is exposed to the front end, REST responses, or page source.
• Public git repositories, client-side mobile apps, or anything a customer can decompile.

Do keep the key:

• On your own server, used only for outbound calls from that server to api.code-heaven.com.
• In an environment variable or secrets manager, never hard-coded in distributed plugin source.

Your plugin ships to thousands of customer servers. The vendor key must never travel inside that plugin package. Instead, the customer's site calls your licensing proxy (or you embed a build-time secret you control), and your server holds the vendor key. If your architecture requires the customer's site to talk to Code Heaven directly, scope a per-product proxy on your own infrastructure rather than shipping the raw vendor key.

With authentication in place, move on to the Quickstart to validate your first license.