Neulock Partner API (v1)

Author: Lucas Neves

Version: 1.0.0

First published: February 6, 2026

Last updated: February 6, 2026

This API allows partners to grant, revoke, check, and report user entitlements for Neulock Business.

Base URL: https://partner.neulock.app
Version: v1
Authentication: Bearer token with API key
Time basis: UTC
Identifiers: tenantId and userId are partner-defined identifiers; Neulock stores only hashed values.

Authentication

All endpoints require partner authentication.

Send your partner API key using the Authorization header with the Bearer scheme:

Authorization: Bearer <API_KEY>

Example:

curl -i \
  -H "Authorization: Bearer $NEULOCK_PARTNER_API_KEY" \
  https://partner.neulock.app/api/v1/entitlements/acme-corp/user-123

If authentication fails:

401 Unauthorized

Entitlements

Resource

/api/v1/entitlements/{tenantId}/{userId}

Represents the entitlement of a specific user within a tenant.

Entitlements are:

idempotent
binary (entitled / not entitled)
time-tracked internally for reporting

Create / Ensure Entitlement

Grants entitlement to the user if not already granted.

PUT /api/v1/entitlements/{tenantId}/{userId}

Responses

Status	Meaning
`201 Created`	Entitlement was newly created
`204 No Content`	Entitlement already existed (no change)
`401 Unauthorized`	Authentication failed

Notes

Safe to retry
No request body
No response body

Revoke Entitlement

Ensures the user no longer has entitlement.

DELETE /api/v1/entitlements/{tenantId}/{userId}

Responses

Status	Meaning
`204 No Content`	Entitlement was revoked or did not exist
`401 Unauthorized`	Authentication failed

Notes

Idempotent
Safe to retry

Check Entitlement

Checks whether the user currently has entitlement.

GET  /api/v1/entitlements/{tenantId}/{userId}
HEAD /api/v1/entitlements/{tenantId}/{userId}

Responses

Status	Meaning
`204 No Content`	User has entitlement
`404 Not Found`	User does not have entitlement
`401 Unauthorized`	Authentication failed

Notes

HEAD is preferred for existence checks
No response body is returned

License Reporting

Resource

/api/v1/licenses/{tenantId?}/{userId?}

Returns the number of unique users who had entitlement at any point during a given month.

This includes users whose entitlement:

started before the month and ended during it
started during the month
started during the month and is still active

Get Monthly License Count

GET /api/v1/licenses
GET /api/v1/licenses/{tenantId}
GET /api/v1/licenses/{tenantId}/{userId}

Query Parameters

Name	Type	Required	Description
`month`	string (`YYYY-MM`)	No	Month to report on (UTC). Defaults to last month

Examples

GET /api/v1/licenses
GET /api/v1/licenses/acme-corp
GET /api/v1/licenses/acme-corp/user-123
GET /api/v1/licenses?month=2026-01

Response

{
  "month": "2026-01",
  "licenses": 42
}

Response Fields

Field	Type	Description
`month`	string	Reporting month (`YYYY-MM`)
`licenses`	number	Count of unique users with entitlement during the month

Status Codes

Status	Meaning
`200 OK`	Report generated
`204 No Content`	`HEAD` request
`400 Bad Request`	Invalid `month` format
`401 Unauthorized`	Authentication failed

Semantics

A user is counted if any entitlement session overlaps the month:

session.start_time < month_end
AND (session.end_time IS NULL OR session.end_time >= month_start)

Counting is done per unique user, not per entitlement session.

CORS / Preflight

All resources support OPTIONS.

Allowed methods:

Entitlements: OPTIONS, HEAD, GET, PUT, DELETE
Licenses: OPTIONS, HEAD, GET

Error Responses

Errors are returned as plain text unless otherwise stated.

Example:

400 Invalid month. Use YYYY-MM.

Design Notes (Informational)

No personal identifiers are stored in plaintext.
Entitlements are tracked as time spans for accurate historical reporting.
The API is safe for retries and concurrent calls.