BusinessMode
Sign inGet started

Quickstart

Create a License, assign a seat, and check access from your backend using HTTP.

API base URL for this environment: https://api.businessmode.io/v1

Your application keeps its own users, authentication, and sessions. BusinessMode identifies a customer user by the stable external ID your backend supplies.

1. Create a Workspace and Project

Create a BusinessMode account, then complete onboarding in the product. Create a Workspace for account-level billing and a Project for your integration. Workspace membership and direct Project membership are independent.

2. Create a machine API key

With your Project active, open API Keys. Copy the full bm_sk_... credential during its one-time handoff and store it only on your server. Later management exposes only the prefix. Never embed the key in browser or mobile code.

Set these server-side variables using the API base URL shown above:

Example code
BUSINESSMODE_API_URL="PASTE_API_BASE_URL_SHOWN_ABOVE"
BUSINESSMODE_API_KEY=bm_sk_...
LICENSE_ID=your-license-uuid

The key and License ID above are placeholders. Use the API origin configured for your environment.

3. Create an Organization, Entitlement, and License

Use the product to create an Organization for your customer and an Entitlement such as premium for a capability. Create a License for that Organization, include the Entitlement, and set seat capacity and validity. A License distributes capabilities; an Entitlement is not itself a seat.

4. Assign a customer user

Your backend assigns a seat to a stable external user ID. Generate one UUID for this logical mutation. If the HTTP response is lost, retry the same path, body, and Idempotency-Key.

Example code
ASSIGNMENT_REQUEST_ID=00000000-0000-4000-8000-000000000001
curl --request POST "$BUSINESSMODE_API_URL/licenses/$LICENSE_ID/assignments" \
  --header "Authorization: Bearer $BUSINESSMODE_API_KEY" \
  --header "Idempotency-Key: $ASSIGNMENT_REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{"externalUserId":"customer_user_123"}'

Use a newly generated UUID for each new logical assignment, not the illustrative value above. The response contains the canonical assignment. See the assignment operation and retry rules.

5. Check access

When your application needs to gate a capability, your backend asks BusinessMode about the external user and Entitlement key:

Example code
curl --get "$BUSINESSMODE_API_URL/access" \
  --header "Authorization: Bearer $BUSINESSMODE_API_KEY" \
  --data-urlencode "externalUserId=customer_user_123" \
  --data-urlencode "entitlementKey=premium"

Read hasAccess from the response. Your application still authenticates its user; BusinessMode answers whether that external ID currently has the capability. See the access operation and access model.

About the repository SDK

The codebase contains a typed @businessmode/sdk client, but its package is currently private and is not distributed on a public package registry. The HTTP examples above are the externally usable baseline. Repository contributors can use the internal SDK; its automatic initial Idempotency-Key generation is not a substitute for retaining the same key across ambiguous retries.