API and developers

Authentication

How to authenticate requests using API keys

Every request to the Business API must include a valid API key in the X-API-Key header.

Obtaining an API Key

API keys are managed from the YaVendio Dashboard — there is no programmatic endpoint for key management.

  1. 1

    Navigate to API settings

    Log in to the YaVendio Dashboard and go to Settings → API Keys.

  2. 2

    Create a new key

    Click "Create API Key". Assign a descriptive name (e.g., "ERP Integration").

  3. 3

    Copy your key

    The full secret key is shown only once at creation time. Copy it and store it securely. Afterwards the dashboard only keeps its prefix (yv_live_v1_Xk3Rt9pQz...) for identification.

Key Format

A key looks like yv_live_v1_ followed by 43 random characters:

yv_live_v1_Xk3Rt9pQzL7mN2vB8cD4fG6hJ1kM5nP0rS9tU3wY7xZ

The dashboard always creates live keys. There is no sandbox environment: a test key would operate against the same production data, so there is no "safe" version of the credential to experiment with.

Using the API Key

Include the key in every request via the X-API-Key header:

curl -H "X-API-Key: yv_live_v1_your_api_key" \
  https://api.ya.onl/v1/orders

Scopes

A key created in the dashboard has access to every endpoint except order creation: it is created with no scopes assigned, which grants every scope but orders:write.

The scope model itself is already implemented in the API. Each endpoint declares its own — orders:read, orders:write, products:read, products:write, conversations:read, contacts:read, company:read, webhooks:read, webhooks:write, outbound:send, outbound:read — and each endpoint's reference page names the one it needs.

orders:write lets a key record sales with POST /v1/orders, and it is the only scope a key does not hold by default: only a key it was explicitly granted to when it was created holds it. A key missing the scope an endpoint requires gets 403 Forbidden:

{
  "type": "ForbiddenError",
  "detail": "Missing required scope: orders:read"
}

Treat every key as a full-access credential: create one per integration and delete it when you stop using it. A key with orders:write also records sales on your store's behalf: grant it only to the integration that sends them.

Key States

Keys visible in the dashboard have two possible states:

State Meaning
Active The key is valid and accepts requests
Revoked The key has been deactivated and all requests are rejected with 401

Dashboard Information

The API keys table in the dashboard shows:

  • Name — the name you assigned when creating the key
  • Scope — always shows "Orders & Products" today, because every key is created with full access
  • Status — Active or Revoked
  • Secret Key — prefix only (yv_live_v1_Xk3Rt9pQz...)
  • Created — when the key was created
  • Last used — timestamp of the last API request made with the key

To delete a key, click the trash icon next to it. This action is irreversible — any integration using the key will immediately start receiving 401 errors.

Error Responses

Status When
401 Unauthorized API key is missing, invalid, expired, or revoked
403 Forbidden The key is valid but lacks the scope the endpoint requires. With a dashboard key you will only see it on POST /v1/orders, when the key lacks orders:write 
{
  "type": "UnauthorizedError",
  "detail": "Invalid or missing API key"
}

Best Practices

Never expose your API key in client-side code (browser JavaScript, mobile apps). Always call the API from your backend.

  • Use environment variables to store API keys — never hardcode them in source code.
  • Create separate keys for each integration or environment (development, staging, production).
  • Rotate keys periodically — delete the old key and create a new one from the dashboard.
Need help?