Authentication and API keys

Every API request carries one of the store's API keys. The key identifies the store and says what the request may do. There is no user, password or session: whoever holds the key has the access.

Create a keyCopy Anchor Link

1. Open General›Settings › Developers.
2. Create a new key. Give it a name that says where it will be used, such as "ERP" or "Production server", and choose the scopes.
3. Copy the full value, vk_live_…. It is shown only once. After that, the dashboard shows only the last four characters.

Each key is pinned to an API version, the current one on the day it was created. See Version.

The step by step with what the dashboard shows is in Developers: keys and logs.

Key formatCopy Anchor Link

vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh

Letters and digits, nothing else. A key with any other shape is refused with 401 invalid_api_key before the database is consulted.

Only the live prefix exists. Vipter has no test mode; see Testing without a test mode.

ScopesCopy Anchor Link

A key can have one or both scopes. A request to an endpoint without the required scope gets 403 insufficient_scope. For an integration that only reads data, create the key with read only.

Use the keyCopy Anchor Link

Send the key in the Authorization header, as a Bearer token:

curl https://api.vipter.com/v1/account \
  -H "Authorization: Bearer vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh"

The API also accepts HTTP Basic with the key as the user and an empty password, the same habit as Stripe's examples with -u. The two forms are equivalent:

curl https://api.vipter.com/v1/account \
  -u vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh:

The trailing colon tells curl the password is empty. Without it, curl prompts for a password in the terminal.

The key works for https://api.vipter.com/v1 and for https://app.vipter.com/api/v1; see Base URL.

Store the keyCopy Anchor Link

• Keep the key in an environment variable or a secrets vault. Never in source code, in a repository or in a page served to the browser.
• Use one key per system and per environment. If one leaks, you revoke only that one.
• The API does not accept browser calls with the key: anyone opening the page would have the key. Call the API from your server.
• If a key showed up somewhere public, revoke it right away and create another. Vipter has no way to recover a key's value: only the hash of the secret is stored.

Revoke a keyCopy Anchor Link

In the key list, use the revoke action. The key stops working immediately: the next request with it gets 401 api_key_revoked. It cannot be undone. To rotate a key without stopping the integration, create the new one, deploy, check in the last-used column that the old one is no longer used, and only then revoke the old one.

Revoked keys stay in the list, for the history. The request logs show which key made each call.

The API is on for every storeCopy Anchor Link

There is nothing to request: every active store answers the API as soon as it has a key. Vipter can switch the API off for one store, for abuse or an account issue. The Developers tab then shows a notice and every request, even with a valid key, gets 403 api_not_enabled. 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.

The API also only answers for active stores. A suspended store, or one in another state, gets 403 project_inactive.

Testing without a test modeCopy Anchor Link

Vipter has no test keys and no separate environment. Testing happens in the same store, with a payment provider's test connection:

1. Under Payments›Providers, create a connection with Test connection turned on. It uses the provider's test environment and charges nobody for real.
2. Make a purchase through the checkout with that connection. See Test your store.
3. Retrieve the order through the API. An order that went through a test connection comes with "livemode": false. Customers, subscriptions, offers and products have no connection, so they come with "livemode": true.

Because the test happens in the real store, test orders show up in the dashboard and in the reports next to the real ones. Use the livemode field to tell them apart in your system.

Authentication errorsCopy Anchor Link

All of them come in the standard error format. A 401 is about the key; a 403 is about what the key may do or about the store.

Requests without a valid key are limited by IP address, at 10 per minute. Beyond that, the answer is 429 rate_limit until the window clears. This protects against key guessing and does not affect authenticated calls, which have their own limit.

What to do nextCopy Anchor Link

• Read the API conventions: format, errors, pagination and limits.
• Make your first call and see every object in the API reference.