Product API reference

Use the HTTPS address of your Asoju installation. The examples use the reserved domain asoju.example.test and placeholders; they are not working credentials. These endpoints cover product access and product keys. They do not establish product-key authentication for CRM, campaigns, provider connections or every Asoju endpoint.

Authentication and workspace

Catalog, access and key-management requests require your signed-in Asoju session cookie. A product key does not replace that session. From the same-origin application, include the existing session with the request; do not copy session cookies into source code or examples.

Choose the workspace explicitly with organizationId where supported. Access reads and key lists require membership. Creating, updating, revoking or reading an individual organization key requires an organization owner or administrator; platform administrator status alone does not grant membership. Personal key management is restricted to the key's owner. Organization access cannot be used to create a personal key, or vice versa.

Read products and access

An entitlement must be active, its product active, and its validity date unexpired. If linked to a purchase, that purchase must be active, trialing or paid. A free catalog product without a productAccess.id cannot be used in the key-creation request below.

Manage keys

For example, send this JSON from an authenticated session to POST /api/api-keys. Replace the IDs with an existing entitlement and its actual workspace.

{
  "name": "Example server key",
  "productAccessId": "YOUR_PRODUCT_ACCESS_ID",
  "organizationId": "YOUR_ORGANIZATION_ID",
  "permissions": ["read:catalog"],
  "expiresAt": "2099-01-01T00:00:00Z"
}

name is required and contains 1–100 characters. productAccessId is required. Omit organizationId for a personal entitlement. Optional userId must equal the signed-in user. Creation expiry is an optional future ISO datetime; omit it for no expiry.

Permission prefixes are checked against the entitlement: READ allows read, WRITE allows read and write, ADMIN additionally allows delete, admin and *. This is a prefix check before :; these strings are not a promise that an endpoint with that resource name exists. Each product consumer must enforce its own supported operations. Omitted permissions do not establish unrestricted access.

On update, omitted fields retain their values. expiresAt: null removes expiry. permissions: [] clears the permission list; permissions: null retains it. Status accepts ACTIVE, REVOKED or EXPIRED, but a revoked or expired key cannot be reactivated: create a replacement. There is no rotate endpoint; create a new key, update your consumer, then revoke the previous one.

Store the one-time creation secret on your server. Subsequent reads, updates and revocation responses expose a prefix and metadata, not the secret or its stored hash. Do not place keys in URLs, screenshots, client bundles or public logs.

Verify a product key

POST /api/api-keys/verify accepts the key in JSON. This endpoint does not require a signed-in session. It is not an Authorization-header example for key-management routes.

curl --request POST 'https://asoju.example.test/api/api-keys/verify' \
  --header 'Content-Type: application/json' \
  --data '{"key":"YOUR_PRODUCT_API_KEY","productSlug":"YOUR_PRODUCT_SLUG"}'

productSlug is optional; include it to require that specific product. A successful 200 response has valid: true, apiKey with id, name and recorded permissions, product with id, name and slug, and accessLevel. No full key or hash is returned. The accepted verification records lastUsedAt after applicable organization policies permit the request.

Unknown, revoked, expired, wrong-product or inactive-entitlement keys return 401 with valid: false and a message. Verification checks the key's current ownership against its entitlement. A successful verification confirms this key and entitlement; it does not send mail, execute a provider request or prove an integration is configured.

Errors, limits and retry

Malformed input is rejected by the request validator (400); missing session is 401, denied membership, ownership or entitlement is 403, and an absent product, access or key can be 404. Unexpected failures are 500. Do not assume a failed creation was never committed: check the authorized list before creating another key, because creation has no idempotency key.

The installation's general limit defaults to 100 requests per 60 seconds, shared by the resolved client identity. Organization policies can impose additional limits. Use the actual X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After headers instead of treating that default as a dedicated allowance per key. 429 means wait before retrying. A temporarily unavailable limit store can return 503 with Retry-After. These limits do not describe external providers' quotas.

Return to account and workspace help for selecting the correct organization.