API

WAMA REST API guide

Integrate your systems with WAMA using the HTTPS JSON API at https://www.wama.cloud.

This page covers API key authentication, multi-tenant point-of-sale context, pagination, and errors. For request and response fields, open the interactive OpenAPI reference (full screen).

Getting started

1. Create an API key in the WAMA web app (Settings → Integrations). Prefer read only unless your integration must write data.
2. Call /api/** with header Authorization: Bearer <api_key> (or X-Api-Key).
3. Use the interactive API reference for request/response fields.

Base URL: https://www.wama.cloud

Authentication

Create an API key

1. Sign in to WAMA in the browser as an account administrator (ROLE_USER / Administrator).
2. Open Settings → Integrations.
3. Choose Create API key, set a name, the point of sale the key is bound to, a scope, and an optional expiry date.
4. Copy the key immediately — the full secret is shown only once.

Key format:

wama_<publicId>_<secret>

Store it like a password (environment variable or secret manager). Never commit keys to source control or paste them into public tickets.

Scopes

Prefer read only for reporting, sync, and AI assistants unless writes are required.

Call the API

Send the key as an HTTP header on every request:

Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET

Optional alias (same key):

X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET

If both a JWT Authorization: Bearer … and X-Api-Key are present, the JWT wins and X-Api-Key is ignored.

Example:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Equivalent with X-Api-Key:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Revoke or rotate

Revoke keys from Settings → Integrations. Revoked or expired keys return 401. Create a new key to rotate; update your client and revoke the old one.

API keys cannot create, list, or revoke other API keys — manage keys only from the web app (session login).

Connect WAMA (PKCE)

MCP hosts can obtain a key without paste using OAuth Authorization Code + PKCE against the public client wama-mcp (no client secret). After browser login and consent (point of sale + scope, default read), the token response’s access_token is the long-lived wama_… key (also returned as integration_api_key for compatibility).

For simple setup in each AI tool, see the MCP guide. Paste from Settings → Integrations remains fully supported.

Point of sale (tenancy)

All inventory, sales, and related data belong to a point of sale (POS).

Each API key is bound to one POS at creation. Requests authenticated with that key always use that POS — you do not switch POS with POST /api/point-of-sales/... when using an API key.

Create a separate key per warehouse/store if you need multiple POS contexts.

Pagination

List endpoints accept Spring Data pagination query parameters:

Successful list responses include:

Errors

Most failures return JSON shaped like:

{
  "message": "error.validation",
  "description": "Optional human-readable text",
  "fieldErrors": [
    {
      "objectName": "productDTO",
      "field": "barcode",
      "message": "NotNull",
      "defaultMessage": "must not be null"
    }
  ]
}

Parameterized domain errors may return { "message": "...", "params": ["..."] } instead.

Common auth outcomes:

Conventions

• JSON request and response bodies (Content-Type: application/json)
• Dates as ISO-8601 with offset (e.g. 2026-03-15T10:30:00.000Z)
• Money as decimal amounts paired with currency objects where applicable
• Ids are server-assigned; omit them (or send null) when creating resources

Example: list products

curl 'https://www.wama.cloud/api/products?page=0&size=20&sort=timeModified,desc' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET'

OpenAPI reference

Browse every public endpoint: