↑↓ selectEnter openEsc close

    1. Elbuz

    Legacy Elbuz API (v1): key and moving to API v2

    4 min readUpdated

    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

    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-inapi/login → api_token in the body or URLAuthorization: Bearer elbz_… header on every request, no session
    Rightsadministrator rights, account-widethe rights of the employee the key is issued for: windows, fields, “Data scope”
    Changesapplied immediatelydepending on the key mode: a request in “Pulse” (202) or immediately
    Errorscode 200, three different body formatsthe real HTTP code, RFC 9457 format
    Pagespage, max_rows up to 500cursor, limit up to 200
    Retry after a breakcreates a duplicateIdempotency-Key — no duplicate
    Limit30 per minute as a minimum interval120 per sliding minute, RateLimit headers

    How to move the key

    1. Open your v1 key's card in the “API & access tokens” window.
    2. 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.
    3. 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.
    4. Copy the new key — it is shown only once.
    API v2 key card: on behalf of an employee, data changes mode, safety limit and the new key
    1On behalf of
    2Data changes
    3Safety limit: changes per hour
    4Current key
    5Read only
    1. On behalf of — whose permissions and data the key gets. Other employees are visible only to someone with access to the users window.
    2. Data changes — “Ask” (every change waits in Pulse) or “Do it myself”. Only “Management” can switch it.
    3. Safety limit — after this many executed changes per hour the key returns to “Ask” on its own.
    4. The new key is shown once: copy it with the Copy button before closing the window.
    5. 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

    v1v2
    api/login + api_tokenAuthorization: Bearer header
    scope/describe scope=XGET /api/v2/openapi.json or GET /api/v2/
    scope/get product / product_price / document / contractor / contractor_group / company / category / manufacturer / attribute / attribute_blockGET /products, /supplier_products, /documents (+ /document_items?filter[document_id]=), /contractors, /contractor_groups, /companies, /categories, /manufacturers, /attributes, /attribute_groups
    scope/get articleGET /articles
    scope/get document_type / document_status / document_payment_status / document_delivery_status / stock_status / warehouse / store / currency / languageGET /document_types, /document_statuses, /payment_statuses, /delivery_statuses, /stock_statuses, /warehouses, /stores, /currencies, /languages; new: /payment_types, /delivery_types
    scope/add document with postingPOST /documents, then POST /documents/{id}/sign
    scope/add X, X/add_batchPOST /X with Idempotency-Key, one record at a time
    scope/update X, X/updatePATCH /X/{id}
    scope/delete X, X/deleteDELETE /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 productGET /products?q=…
    scope/add contractor_pricePOST /price_lists/{id}/import — a background task
    scope/add mail_sendPOST /mail_messages/{id}/reply — always via “Pulse”
    scope/add document_extended, scope/get print_templateno 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 fieldRequest parameterWhat it does
    “User”usernamesign-in name
    “Access Key”keythe 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 seeWhyWhat to do
    New key: api/login returns “incorrect key”the key was created for API v2 and has no “Access Key” fieldsend requests to /api/v2/… with the Authorization: Bearer header (API v2)
    Reading works, writing is rejectedthe key has “Read only”; the checkbox applies to all routes, including the old onesclear the checkbox — it takes effect at once, no need to sign in again
    The key stopped working although it is activethe day after the “Access end date” has comemove the date or clear the field — then the key never expires
    After moving to v2, part of the data disappeared from responsesa v2 key sees only its employee's windows and fieldsopen 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
    System settings window, Other settings section with the set of tiles including API and access tokens
    1API and access tokens
    2Other settings
    1. API and access tokens — opens the list of API keys.
    2. Other settings — collects windows that are not in the main menu.

    Related topics

    Was this article helpful?

    Missing a feature? Tell us.

    We will add it for free if other users need it too.

    If only you need it, we will agree on it separately.

    Article contents

    Suggest an improvement

    Try Elbuz free