API users and tokens

An API user is how your own code, an integration partner or a script talks to the Smooth POS API. Each API user has its own token and its own set of rights, so you can give every integration exactly the access it needs and switch one off without touching the others.

Create an API user

1. Go to Admin › Users › API Users and select New API User.
2. Give it a Name that says who or what uses it, like "Nightly sync" or "Klaviyo".
3. Choose its rights (see below), then select Save.
4. Open the API user again from the list. The Token field now shows its token, hidden. Select Show to see it, or Copy to copy it to your clipboard.

Choose its rights

Rights are grouped by area, such as Products, Sales, Customers, Inventory and Integrations. Each row has two switches:

• View lets the API user read that area, like listing products.
• Manage lets it create, change and delete there too. Turning on Manage also keeps View on.

Use Search rights to find a right by name, and Select all or Clear to change a whole group. The count beside each group shows how many of its rights are on.

👍

Give each integration only what it needs

A nightly stock export needs to view products and inventory, not manage sales. Small sets of rights limit the damage if a token leaks, and make it obvious what each integration does.

Use the token

Send the token in the X-Smoothpos-Auth header on every request:

curl https://api.smoothpos.net/products.json \
  -H "X-Smoothpos-Auth: YOUR_TOKEN"

The token you copy is ready to use as it is: don't encode or change it. A request for something the API user doesn't have the rights for is refused.

Keep tokens safe

• Treat a token like a password. Keep it in your integration's secret store, never in source code, screenshots or tickets.
• One API user per integration. When a partner stops working with you, delete their API user and nothing else breaks.
• Delete to revoke. Deleting an API user (Options › Delete on its page) stops its token working straight away. To replace a token that may have leaked, create a new API user, move your integration to it, then delete the old one.

Glue jobs don't need an API user: the API Request step calls the API as your company for you.