Developers: keys and logs

The Developers tab is where the store connects to an external system through the API: your SaaS, an ERP, a CRM or a script of your own. Here you create the keys the system uses to get in and see the record of every call it made. What the system can do with the key, and how to program the integration, is in the developer section, starting at Developer overview.

Open the tabCopy Anchor Link

Open General›Settings › Developers. The tab has two parts: the API keys and the request logs.

API keysCopy Anchor Link

An API key is the password your system uses to talk to the store. Whoever has the key reaches the store's data, so treat it like a password.

Create a keyCopy Anchor Link

1. Click the create-key button.
2. Give it a name that says where it will be used, such as "ERP" or "Production server".
3. Choose the scopes: read allows querying customers, subscriptions, orders, offers and products; write will allow creating and changing data once the write endpoints are released. For a system that only reads, tick read only.
4. Copy the key, which starts with vk_live_. It is shown only once: close the window and it can no longer be seen. If you lose it, revoke it and create another.

Hand the key to whoever programs the integration through a secure channel, never by email or plain-text message. The programmer should keep it in an environment variable, as Authentication and API keys explains.

The key listCopy Anchor Link

Each key shows its name, its last four characters (the rest is not stored), its scopes, the API version it was created on, when it was created and when it was last used. The last-used date tells you whether the integration is alive and, when rotating a key, whether the old one has stopped being used.

Revoke a keyCopy Anchor Link

Use the revoke action on the key's row. The key stops working immediately and the system that used it starts getting an authentication error. It cannot be undone. To rotate a key without stopping the integration: create the new one, ask for it to be deployed, wait for the old one to go unused, and only then revoke the old one.

Request logsCopy Anchor Link

Every call a system makes to the API is recorded: the date and time, which key it used, the method and path (such as GET /v1/orders), the response code, the duration and, when it failed, the error type and code. Each row has a req_… identifier, the same value the API returns in the Request-Id header.

The logs are for:

• Confirming that the integration is calling the API, and with which key.
• Seeing why a call failed without needing access to the other system's logs. The error code is explained under Errors.
• Finding a specific call by the req_… the developer or support gave you.

The logs are kept for 30 days and then deleted. Calls made without a valid key do not appear: without the key, Vipter cannot tell which store the call would belong to.

The logs show what was requested and the result, not the content of the responses. Customer data is not duplicated here.

What "API turned off" meansCopy Anchor Link

The API is on in every active store; there is nothing to request. Vipter can switch it off for one store, for abuse or an account issue. The tab then shows the notice, keys cannot be created, and any call, even with a valid key, gets the api_not_enabled error. To turn it back on, contact Vipter support and give the store's name. Existing keys work again as soon as the API is back on.

Common problemsCopy Anchor Link

• The integration gets an authentication error right after the key was created

  Check that the key was copied whole, without leading or trailing spaces, and that the API was not switched off for the store. If the key shows as revoked in the list, create another.

• The key shows as never used, but the system says it is calling

  The system may be calling another address or using another key. Compare the address and the key's last four characters in the system with the list. The last-used date can take up to a minute to appear.

• A call shows a 403 insufficient_scope error

  The key lacks the scope the call requires. Create a key with the right scope and swap it in the system.

• Many calls with a 429 error

  The system went past the limit of 100 requests every 2 seconds per key. The programmer should honor the Retry-After header; see Rate limits.

What to do nextCopy Anchor Link

• Hand whoever programs the integration the Developer overview and the API reference.
• To receive notices from Vipter in your system, instead of polling, set up a webhook.