Set up API access: Client ID, contact keys and test tokens

To connect another system to Allmoxy through the API you need three things: your shop's Client ID and Client Secret (generated once at Settings > Integrations > API), a contact key that says which contact the integration acts as and what it may read or change, and, while testing, a token that lasts one hour. This article walks through all three, where the API reference and the Postman collection are, how to change or switch off a key later, and what to check when calls are refused.

Applies to: shops with the API add-on. Opening Settings > Integrations > API needs the Manage Integrations permission; generating credentials and tokens needs Manage API key, and seeing them needs at least View API key. Creating a key on a contact also needs Modify Permissions.

In this article

Before you start
Get your Client ID and Client Secret
Create a contact key for the integration
Get a test token and the sample request
Read the API reference and try calls in Postman
Manage keys
If calls are refused
Things to know

Before you start

An API, or application programming interface, is a way for different software systems to communicate. To use one you present credentials, and Allmoxy's API uses your shop's Client ID and Client Secret together with a contact key. These credentials are what keep the API and the data behind it to authorized users; without them, anyone could reach your data. Once you have generated them, keep them secure and share them only with the people who need to work with the API.

Access to the API is an add-on with a monthly subscription that comes with a sandbox (test) site, so your developer can build against a copy before touching live orders. Ask your Customer Success Manager or support@allmoxy.com. Without the add-on, Settings > Integrations > API shows the API sign-up page instead of your credentials.

Limit who can see and manage the credentials. The permissions are in the Integrations group on an employee's contact record (Contact > Edit > Integrations Permissions): Manage Integrations opens the API page, Manage API key allows generating and regenerating, and View API key allows viewing only. Give Manage API key to as few people as possible.

Get your Client ID and Client Secret

Go to Settings > Integrations > API.
Click Generate Client ID and Secret.
Review the pop-up to make sure you are ready to generate (or regenerate) and confirm.
Both values appear on the page, masked, with reveal and copy buttons. You can come back here any time you need them for reference.

Generate them once. The page also offers a regenerate option, and regenerating cuts off every existing integration at once: the app warns that all existing consumers lose access, and each integration must be given the new Client Secret before it works again. Treat regenerating as the fix for a leaked secret, not a routine step.

Create a contact key for the integration

A contact key is the credential an integration presents with the Client ID and Client Secret. It identifies the application making the request, so you control exactly which data it can read or change and can audit what it did. Each key belongs to one contact and acts as that contact, with only the access you switch on.

Open the contact who will act for the integration (a dedicated contact such as "Inventory sync" is easier to audit than a person's account) and click Edit.
Scroll down to the API Access section and click Create Key.
Give the key a unique name for internal reference.
For each area of data (orders, companies, products and so on), switch on only what the integration needs: Create, Read, Update or Delete.
Click Create Key.

You can now share the key, the Client ID and the Client Secret with the developer who needs them, and with no one else. A key made on a customer contact never reaches admin-only areas, whatever its switches say, so a key for your own systems belongs on an employee contact.

Get a test token and the sample request

Every API call carries a short-lived token that the integration obtains with the Client ID, the Client Secret and the key. While you are testing, the API page gives you one without writing code.

On Settings > Integrations > API, click Generate API Authorization Token.
Copy the token into your test tool. It is good for 3,600 seconds (one hour), and the page counts down the time left.
When it expires, generate another. Only the token changes; the Client ID and Client Secret stay the same.

A token generated at 9:00 works until 10:00. At 10:05 a call with it comes back as not signed in, so generate a new one and try again. The page also shows a copyable sample request (Get Token Example) that your developer can use as the pattern for fetching tokens in their own code.

Read the API reference and try calls in Postman

The current reference is the hosted API documentation: click View API Documentation on the API page (it opens apidocs.allmoxy.com). It lists every resource and call with its parameters and responses, and it is rebuilt from the API itself on every release, so it is always the version to trust.

To try calls without writing code, use Postman. It lets you view all the data in a call and test specific calls against your sandbox. To get Allmoxy's collection, open Postman, choose Import Collection, and use this link. The collection includes the token request, so paste in your Client ID, Client Secret and key and you can fetch a token and list your orders in a few minutes. The collection is a static file and the hosted reference is updated more often, so when the two differ, the reference is right.

Manage keys

Every contact key is listed in one place: on the API page, open the options menu and choose Manage Contact Keys. The same actions are on the contact's API Access section. Each key offers:

Edit Permissions: change the switches on a key that keeps the same purpose, then save. The key itself does not change, so the integration keeps working.
Generate New Key: use this when the purpose and permissions are changing from the existing key. A new key is issued for that contact and the old one stops working, so give the developer the new key.
Disable Key: the API work is done, but you no longer want access granted with that key. Nothing is lost, and you can turn it back on.
Activate: turn a disabled key back on.
Delete Key: the key was never used, or is no longer needed at all. Delete only when you are sure nothing still uses it.

If calls are refused

One kind of call is "not allowed" while others work: open the key and check its switch for that area and action (for example Update on orders). A key on a customer contact can't reach admin-only areas no matter what is switched on.
Every integration stopped at once: someone regenerated the Client ID and Secret. Give each integration the new Client Secret.
Calls worked and then stopped with a sign-in error: the token expired. Generate a new one; nothing else has changed.
A call that the reference says exists comes back as not found: check you are calling the site named in the reference (sandbox or live) and the path shown there.

If you still can't get through, open the support chat and tell us the contact the key belongs to, the call you are making and the exact message. Never paste the key, the Client ID or the Client Secret into a support ticket or chat; we never need them.

Things to know

Generate the Client ID and Client Secret once. Regenerating cuts off every integration at once; each needs the new secret.
A key acts as its contact. It gets only the areas and actions you switch on, and a key on a customer contact never reaches admin-only areas.
Test tokens last one hour (3,600 seconds). The page counts down; generate another when it runs out.
The hosted API documentation is the reference, rebuilt on every release. The Postman collection is a convenience for testing.
Keep secrets out of tickets. Share the key, Client ID and Client Secret only with the developer who needs them.
Manage API key is powerful. Give it to as few people as possible; View API key is enough for most.