CartDocs

API keys and authentication

Paid plans

Make an API key with only the permissions a tool needs, send it as a bearer token, get a token by sign-in, and revoke a key.

In the admin: SettingsAPI keys

On this page

Every API call is made with a key. A key belongs to the person who made it and can only do what that person may do in the admin, and only what was ticked for the key. Make one key per tool, so you can revoke one without stopping the others.

Make an API key

  1. Go to Settings and open API keys. You may be asked for your password again.
  2. Press New key.
  3. Give it a Name, for example the tool that uses it.
  4. Optionally set a Last day. The key stops working at the end of that day. Without it, the key does not expire.
  5. Under Permissions, tick what the key may do, for example See orders or Adjust stock. You can pick only permissions you have yourself. With none ticked, the key can only read who it belongs to.
  6. Press Create key.

The key is shown once under Your new key. Copy it now and keep it somewhere safe, such as your tool's secret settings. It is not shown again. A staff key starts with ics_.

The key list

Your shop's API keys lists every key with its Name, the start of the Key, who it was Created by, its Permissions, when it was Last used, when it Expires and its Status: Active, Expired or Revoked.

Revoke a key

Press Revoke on the key's row and confirm. Tools that use this key stop working at once. This cannot be undone. Make a new key if the tool still needs access.

Revoke a key at once if it may have leaked, for example when it was pasted in a public place.

Who can make keys

Making and revoking keys needs Make and revoke API keys, which the Owner and Administrators hold. If the person who made a key is removed or disabled, their keys stop working too.

Send the key

Send the key in the Authorization header of every call, as a bearer token:

GET /api/v1/orders HTTP/1.1
Host: api.ixxocart.com
Authorization: Bearer ics_your_key_here

A missing or wrong key gets 401 with the code unauthenticated. A key without the needed permission gets 403 with forbidden. A shop whose plan has no API gets 403 with feature_not_available.

Check a key with /me. It answers with the key's type, its permissions, the shop and the person behind it:

GET /api/v1/me HTTP/1.1
Host: api.ixxocart.com
Authorization: Bearer ics_your_key_here

Get a token by signing in

A tool that signs in as a staff member, for example a script you run by hand, can swap an e-mail address and password for a token:

POST /api/v1/auth/token HTTP/1.1
Host: api.ixxocart.com
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your password",
  "totp": "123456",
  "scopes": ["orders.view", "inventory.*"],
  "name": "Stock script"
}
  • totp is the code from your authenticator app, or a recovery code, when you use two-step sign-in.
  • scopes are permission keys such as orders.view, or patterns such as orders.*. Without scopes, the token can only call /me.
  • name is shown in the key list.

The answer holds the token, shown once, and when it expires_at. A token made this way lasts 90 days and shows in the key list, where you can revoke it like any key.

A wrong e-mail or password gets 401 invalid_credentials. Without a needed code you get two_factor_required: send totp too. If your shop requires two-step sign-in and you have not set it up, you get 403 two_factor_setup_required: set it up in the admin first. Sign-ins are limited per address, and too many tries get 429 rate_limited.

Updated 13 November 2026