1. Bootstrap
The customer enters the license key. The application may assert its configured Product UUID or slug; it does not need the customer to copy one.
2. Persist credentials
Store the installation token and certificate securely after activation.
3. Validate
Call validate periodically and replace the locally stored certificate with the returned one.
POST /api/v1/installations/preflight
No API key or installation token is required. Send Content-Type: application/json. The request is read-only.
product · optional- string, Product UUID or slug asserted by the application. If omitted, NEOK License derives the Product from the license.
license_key · required- string, maximum 200 characters; 20–200 ASCII letters/numbers with optional separating hyphens.
installation_identifier · required- string, maximum 255 characters; stable installation identity.
domain · optional- string, maximum 255 characters. Product policy may require it.
server_fingerprint · optional- exactly 64 alphanumeric characters.
app_url · optional- valid URL, maximum 2048 characters.
version · optional- string, maximum 100 characters.
- IP address
- not a request field; the server records the request IP during activation.
curl -X POST https://license.neok.ing/api/v1/installations/preflight \
-H 'Content-Type: application/json' \
-d '{"license_key":"CUSTOMER_LICENSE_KEY","installation_identifier":"membership-installation-1","domain":"membership.example.com","server_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","app_url":"https://membership.example.com","version":"1.0.0"}'
{"success":true,"data":{"eligible":true,"product":{"uuid":"PRODUCT_UUID","name":"Example Product"},"license":{"uuid":"LICENSE_UUID","status":"active"}},"request_id":"REQUEST_UUID"}
Success is HTTP 200. Invalid license or installation policy failures are HTTP 422 validation responses. If an optional product assertion does not identify the license’s actual Product, the response is HTTP 422 with PRODUCT_MISMATCH. Throttling is HTTP 429.
POST /api/v1/installations/activate
No API key or installation token is required. The request fields are the preflight fields plus callback_url. Activation derives the Product from license_key unless the optional product assertion is supplied, then creates or reuses the installation identity, revokes its previous active installation token, and issues a new token and certificate.
callback_url · optional- valid HTTPS URL, maximum 2048 characters; required when Product policy requires a callback.
- Other fields
product, license_key, installation_identifier, domain, server_fingerprint, app_url, and version use the preflight rules above.
curl -X POST https://license.neok.ing/api/v1/installations/activate \
-H 'Content-Type: application/json' \
-d '{"license_key":"CUSTOMER_LICENSE_KEY","installation_identifier":"membership-installation-1","domain":"membership.example.com","server_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","app_url":"https://membership.example.com","version":"1.0.0","callback_url":"https://membership.example.com/license-callback"}'
{"success":true,"data":{"installation":{"uuid":"INSTALLATION_UUID","status":"active"},"installation_token":"nk_install_...","certificate":"BASE64_SIGNED_CERTIFICATE","next_check_at":"2026-01-01T00:00:00.000000Z","grace_until":"2026-01-08T00:00:00.000000Z"},"request_id":"REQUEST_UUID"}
Success is HTTP 201. The response contains no separate license-expiration or product object. The certificate is an opaque base64 value; its signed payload contains certificate, Product, license, installation, validity, online-check, grace, and state-version data.
The Product defaults to an online validation due time 24 hours after activation or validation and an offline-grace timestamp 7 days after that due time. These values are returned as next_check_at and grace_until; use the returned timestamps rather than hard-coding them. Product policy may change these intervals. The certificate validity default is also 24 hours. The API does not authorize an offline request or return an offline success response when the server cannot be reached; any bounded outage behavior is the client application's policy.
POST /api/v1/installations/validate
Authenticate with the installation token returned by activation:
Authorization: Bearer nk_install_...
Content-Type: application/json
The request body is empty. A successful validation response is HTTP 200:
{"success":true,"data":{"valid":true,"code":"VALID","installation_uuid":"INSTALLATION_UUID","status":"active","certificate":"BASE64_SIGNED_CERTIFICATE","next_check_at":"2026-01-01T00:00:00.000000Z","grace_until":"2026-01-08T00:00:00.000000Z"},"request_id":"REQUEST_UUID"}
A valid token causes the certificate to be reissued; replace the stored certificate. An expired, suspended, revoked, blocked, unassigned, not-started, mismatched, or over-limit license returns HTTP 200 with valid:false, the corresponding code, and a resulting installation status. An invalid, expired, deactivated, or normally transferred token is rejected by middleware with HTTP 401 and INSTALLATION_TOKEN_INVALID.
POST /api/v1/installations/deactivate
Authenticate with Authorization: Bearer INSTALLATION_TOKEN. Send an empty JSON body. Success is HTTP 200:
{"success":true,"data":{"deactivated":true,"installation_uuid":"INSTALLATION_UUID"},"request_id":"REQUEST_UUID"}
The installation is marked deactivated and all active tokens are revoked immediately. A repeat request using that token is therefore HTTP 401, not an idempotent success response.
POST /api/v1/installations/transfer
Authenticate with the source installation token. Required fields are destination_installation_identifier (string, maximum 255, no control characters) and idempotency_key (string, maximum 128, only letters, numbers, dot, underscore, colon, and hyphen). Optional fields are domain (maximum 255), server_fingerprint (64 alphanumeric), app_url (URL, maximum 2048), version (maximum 100), callback_url (HTTPS URL), and reason (maximum 255). Product policy must allow transfer.
curl -X POST https://license.neok.ing/api/v1/installations/transfer \
-H 'Authorization: Bearer nk_install_...' \
-H 'Content-Type: application/json' \
-d '{"destination_installation_identifier":"membership-installation-2","domain":"membership.example.com","app_url":"https://membership.example.com","version":"1.0.0","idempotency_key":"transfer-2026-01-01-1","reason":"Server replacement"}'
{"success":true,"data":{"transfer_uuid":"TRANSFER_UUID","installation_uuid":"DESTINATION_INSTALLATION_UUID","installation_token":"nk_install_...","certificate":"BASE64_SIGNED_CERTIFICATE","status":"active","next_check_at":"2026-01-01T00:00:00.000000Z","grace_until":"2026-01-08T00:00:00.000000Z","idempotent":false},"request_id":"REQUEST_UUID"}
Success is HTTP 200. The source installation is transferred and its token revoked; the response credentials belong to the destination. Repeating the same source and idempotency_key for the same destination returns the stored destination credentials with idempotent:true. The transferred source token is accepted only for that recovery retry. Reusing the key for another destination, a disallowed transfer, cooldown, invalid source, or invalid destination returns HTTP 422.
Credential handling
NEOK API key: a developer/server credential for API-key-protected endpoints; it is not used by these installation bootstrap endpoints. Customer license key: the customer secret used only for preflight and activation. Installation token: the credential Membership must persist and send as Authorization: Bearer for validate, deactivate, and transfer. Installation certificate: the signed credential returned by activation/validation for the client’s local licensing use; replace it when validation returns a new certificate. Never log or expose any of these secrets.
Entitlements: activation and validation responses include a deterministic feature map and state. Features are resolved from product defaults and license overrides; inactive or unknown keys are disabled. The signed certificate payload includes the same map, license/product/installation UUIDs, next_check_at, grace_until, and entitlement revision so clients can verify it offline with the product Ed25519 public key.