The legacy Elbuz API (v1) still works for issued v1 keys but gets no new features. New keys are for API v2: an employee's rights, changes confirmed in “Pulse”, no duplicates.
When you need this:
- Your integration uses
api/login— the table maps each call to v2. - A new key returns “incorrect key” — it is a v2 key and won't work with
api/login. - A contractor should see only orders — a v2 key sees only its employee's windows.
- A key must be shut off now — “Active” and the end date also apply to issued tokens.
Where to start: move the key to v2 in its card.
What the legacy API covers
- Moving to v2 — how v2 differs and which v2 resource replaces each v1 operation.
- v1 key — the card fields and three ways to restrict access that take effect immediately.
- API v1 reference — sign-in, the
describe,get,add,update,deleteoperations, filters, errors and ready-made recipes. - What API v1 does to your data — manual edits, a batch that breaks off and is repeated, whose price stays, rollback.
- Ready-made exchanges without a developer — tunnel, marketplaces, scheduled exports.
How to move an integration to API v2
Every response of the legacy carries the headers Deprecation: @1791936000 (14.10.2026) and Link: </api/v2/openapi.json>; rel="successor-version", <https://elbuz.com/en/guide-api>; rel="deprecation". v1 has no shutdown date but gets no new features: a v1 key has administrator rights, no employee rights and no employee action log.
| v1 (this guide) | v2 | |
|---|---|---|
| Sign-in | api/login → api_token in the body or URL | Authorization: Bearer elbz_… header on every request, no session |
| Rights | administrator rights, account-wide | the rights of the employee the key is issued for: windows, fields, “Data scope” |
| Changes | applied immediately | depending on the key mode: a request in “Pulse” (202) or immediately |
| Errors | code 200, three different body formats | the real HTTP code, RFC 9457 format |
| Pages | page, max_rows up to 500 | cursor, limit up to 200 |
| Retry after a break | creates a duplicate | Idempotency-Key — no duplicate |
| Limit | 30 per minute as a minimum interval | 120 per sliding minute, RateLimit headers |
How to move the key
- Open your v1 key's card in the “API & access tokens” window.
- In the “On behalf of” field, choose whose rights the integration gets. The v1 key saw everything — check that the employee has all the needed windows and fields open, otherwise part of the data disappears from responses after the move.
- Click “Create a new key” and confirm “The new key replaces the current one: integrations using the old key will stop working”. The old “User” + “Access Key” and tokens already issued stop working immediately — switch the integration over in the same minute, or create a separate v2 key with “+” and switch when the code is ready.
- Copy the new key — it is shown only once.
1
On behalf of2
Data changes3
Safety limit: changes per hour4
Current key5
Read only- On behalf of — whose permissions and data the key gets. Other employees are visible only to someone with access to the users window.
- Data changes — “Ask” (every change waits in Pulse) or “Do it myself”. Only “Management” can switch it.
- Safety limit — after this many executed changes per hour the key returns to “Ask” on its own.
- The new key is shown once: copy it with the Copy button before closing the window.
- Read only — on for a new key; clear it if the key needs to change something.
A new key is created in “Ask (via Pulse)” mode: every change waits for confirmation in “Pulse”. For an integration that must write immediately (orders from the website, prices from an accounting system), Management sets “Act on its own” in the key card. Details: API v2: changes.
What replaces what
| v1 | v2 |
|---|---|
api/login + api_token | Authorization: Bearer header |
scope/describe scope=X | GET /api/v2/openapi.json or GET /api/v2/ |
scope/get product / product_price / document / contractor / contractor_group / company / category / manufacturer / attribute / attribute_block | GET /products, /supplier_products, /documents (+ /document_items?filter[document_id]=), /contractors, /contractor_groups, /companies, /categories, /manufacturers, /attributes, /attribute_groups |
scope/get article | GET /articles |
scope/get document_type / document_status / document_payment_status / document_delivery_status / stock_status / warehouse / store / currency / language | GET /document_types, /document_statuses, /payment_statuses, /delivery_statuses, /stock_statuses, /warehouses, /stores, /currencies, /languages; new: /payment_types, /delivery_types |
scope/add document with posting | POST /documents, then POST /documents/{id}/sign |
scope/add X, X/add_batch | POST /X with Idempotency-Key, one record at a time |
scope/update X, X/update | PATCH /X/{id} |
scope/delete X, X/delete | DELETE /X/{id} — to Trash, for contacts, documents and articles (in v2 also for deals, tasks, notes, projects); products, categories, manufacturers and attributes can be deleted only in the window |
scope/search product | GET /products?q=… |
scope/add contractor_price | POST /price_lists/{id}/import — a background task |
scope/add mail_send | POST /mail_messages/{id}/reply — always via “Pulse” |
scope/add document_extended, scope/get print_template | no equivalent in v2 |
The routes api/order, api/cart, api/payment, api/shipping, api/coupon, api/voucher, api/reward, api/customer, api/currency have been removed: they were leftovers of the OpenCart storefront, did not work and returned an error. The v1 currency list, api/scope/get/currency, works as before.
v1 key: fields and restrictions
The table below is about the card of a key created before 14.10.2026. It shows the warning “This is an old API (v1) key…”, the “Access Key” field and the “Generate” button. A key you create with the “+” button now is already a v2 key: it has no “Access Key” field and does not work with api/login.
| Key card field | Request parameter | What it does |
|---|---|---|
| “User” | username | sign-in name |
| “Access Key” | key | the secret; the “Generate” button creates it for you |
| “Active” | — | a disabled key is rejected both at sign-in and with a token already issued |
| “Read only” | — | any data change returns an error; reading works |
| “Allowed IP addresses” | — | a list separated by commas, spaces or new lines. Empty means from anywhere |
| “Access end date” | — | the key works up to and including this date; an empty date means no expiry |
| “Note” | — | who the key was issued to and why |
Three fields cut off access immediately, not at the next sign-in. “Active”, “Access end date” and “Read only” are reread from the key card on every request, so they also apply to an issued token: disable the key or pass the date, and the current token stops working without a new sign-in. Handy for revoking a key at once.
v1 key access rights cannot be split by directory. A v1 key is not an app user: departments and permission groups do not apply to it, so one token reads orders, products, contacts and everything else in the account. You can restrict the key only with three card fields: “Read only”, “Allowed IP addresses” and “Access end date”.
If a contractor or third-party program should see only orders, this key won't help: issue a v2 key on behalf of a user in a department that has only the orders window open: the v2 key gets exactly that employee's rights.
Create a separate key for each integration: then revoking one won't stop the others.
When you don't need the API
Before writing an integration, check the ready-made tools — they cover most tasks without a developer:
- A website on a popular — the tunnel writes products, prices and stock straight into the website database.
- A marketplace — ready-made connections already exist for a dozen marketplaces.
- A regular file — scheduled exports to or .
The API is for your own logic: a custom website, an in-house accounting system, an exchange that the ready-made formats don't cover.
Scenarios
The website only pulls stock and prices
Task: the website reads stock and prices from Elbuz and must not change anything in the account.
What to turn on: a separate key for the website with the “Read only” checkbox, and the website server's address in “Allowed IP addresses”. The request is api/scope/get with limit_field=sku,price,quantity, as in the recipe below.
What you get: reading works. Any add, update or delete with this key returns “You do not have permission to modify data” — even if the website code has a bug and tries to write something. A request from another address is rejected both at sign-in and with a token already issued.
Temporary access for an outside developer
Task: a contractor sets up an integration, and access must close when the project ends.
What to turn on: a separate key with the last day of work in “Access end date” and who it was issued to and why in “Note”.
What you get: the key works up to and including that date. The next day neither api/login nor a token obtained earlier lets it in — no need to wait for the session to expire. Finished early? Clear “Active” — same effect. What won't happen: other keys in the account are not affected; each has its own date and checkbox.
You can't limit such a key to particular directories — see how to give a contractor only orders.
Move to v2 without downtime
Task: the integration must keep working while the developer rewrites it for v2.
What to turn on: leave the v1 key alone and create a separate v2 key with “+” on behalf of the right employee. Test the new code with it.
What you get: both keys work in parallel. When the v2 code is ready, clear “Active” on the v1 key — its tokens stop working immediately.
What to do when a key is rejected
| What you see | Why | What to do |
|---|---|---|
New key: api/login returns “incorrect key” | the key was created for API v2 and has no “Access Key” field | send requests to /api/v2/… with the Authorization: Bearer header (API v2) |
| Reading works, writing is rejected | the key has “Read only”; the checkbox applies to all routes, including the old ones | clear the checkbox — it takes effect at once, no need to sign in again |
| The key stopped working although it is active | the day after the “Access end date” has come | move the date or clear the field — then the key never expires |
| After moving to v2, part of the data disappeared from responses | a v2 key sees only its employee's windows and fields | open the needed windows and fields to the employee (step 2 of the move) |
FAQ
Will the legacy API stop working?
There is no shutdown date: v1 keys work as they did. But v1 will get no new features, and “Create a new key” in the card moves the key to v2 with no way back.
Can I have a v1 key and a v2 key at the same time?
Yes. A key created with the “+” button is a separate v2 key, and the v1 key keeps working. This is how you move an integration without downtime (scenario).
The API returns “Warning: Incorrect API Key!” although the key was copied correctly. What should I check?
In the key card: the “User” + “Access Key” pair, “Active” and “Access end date” — the text is the same for all three causes. No “Access Key” field means it is a v2 key. Any other error text comes from a supplier's or marketplace's API, not from Elbuz.
Can I give a contractor an API key that sees only orders?
With a v1 key, no: it reads everything in the account. With a v2 key, yes: issue it on behalf of a user in a department that has only the orders window open (details).
Which Elbuz server IP addresses should I add to a whitelist?
There is no common list: it depends on the account's server. For a supplier API, see the source's “API access settings” window (connecting a supplier); otherwise write to support@elbuz.com. The key's “Allowed IP addresses” field is different: where requests to Elbuz may come from.
Where to find it and who has access
- Menu
- Account → System settings → “Other settings” → “API & access tokens” tile
- Access right
- the “API & access tokens” window in group permissions
- Prepare
- the employee on whose behalf the v2 key will work
1
API and access tokens2
Other settings- API and access tokens — opens the list of API keys.
- Other settings — collects windows that are not in the main menu.
Related topics
- If you are writing a new integration — API v2: keys, rights, format.
- If the integration is still on v1 and you need to find an operation or sort out an error — legacy API v1 reference.
- If the integration writes products and prices to a live account — what API v1 does to your data.
- If you need to connect Claude or ChatGPT to Elbuz — connect an AI assistant.
- If a v2 key's rights need narrowing — users and permissions.
