OptiWMS GraphQL API

Call the OptiWMS GraphQL API from your own systems. Authenticate with an organization API key created under Admin, API keys in the dashboard at app.optiwms.com.

Endpoint and header

POST GraphQL operations to:

https://api.optiwms.com/query

Send the key on every request:

Authorization: Bearer owk_...

The key is shown once at creation. Store it with your integration; OptiWMS never returns it again.

A request for the five newest sales orders:

curl https://api.optiwms.com/query \
  -H "Authorization: Bearer $OPTIWMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ getSalesOrderList(pageSize: 5) { identifier status } }"}'

The answer is a standard GraphQL response: the result under data, and any refusal or failure under errors.

What the key can do

The key acts as the user you chose when you created it. It gets that user's role permissions and warehouse limit. Changing the user's role or warehouses changes what the key can do. Disabling the user or removing them from the organization stops the key within 30 seconds.

Account-administration operations are refused even when the user's role would allow them in the dashboard. The GraphQL error message is exactly:

This operation is not available to API keys; an Administrator does it in the dashboard.

Refused areas include managing API keys, users, roles, memberships and invites, two-factor sign-in, passwords and sessions, organization switching, billing, integration secrets, carrier credentials, pick hand-off tokens and print-device enrollment.

Authentication failures

An unknown, revoked or expired key answers HTTP 401 with an empty body. The same happens when the key's user is disabled or no longer a member of the organization.

Rate limit

Each key may make 600 requests per minute. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the cap the answer is HTTP 429 with Retry-After (seconds until the window resets).

Revocation

Revoking a key in the dashboard stops it within 30 seconds on every API instance (the same window as session revocation). The instance that handled the revoke drops it from its cache at once.

Idempotency

Mutations that support idempotency accept the Idempotency-Key request header on the API key path the same way they do for a signed-in session.

Schema introspection

With an API key you may run GraphQL introspection (__schema, __type) so your tooling can discover the schema. Signed-in dashboard sessions do not get introspection in production. You can also download the schema SDL: schema.graphql.

Creating keys

Keys are created only in the dashboard (or by a signed-in Administrator over GraphQL with the Manage API keys permission). A key cannot create or revoke another key.

Related

• OptiWMS API overview - the Store API for a custom store that OptiWMS has no ready-made integration for
• Dashboard guide: Admin, API keys