> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ya.works/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate requests using API keys

# Authentication

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.

<Steps>
  <Step title="Navigate to API settings">
    Log in to the [YaVendio Dashboard](https://ya.onl) and go to **Settings → API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **"Create API Key"**. Assign a descriptive name (e.g., "ERP Integration").
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Key Format

A key looks like `yv_live_v1_` followed by 43 random characters:

```
yv_live_v1_Xk3Rt9pQzL7mN2vB8cD4fG6hJ1kM5nP0rS9tU3wY7xZ
```

<Note>
  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.
</Note>

## Using the API Key

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

```bash theme={null}
curl -H "X-API-Key: yv_live_v1_your_api_key" \
  https://api.ya.onl/v1/orders
```

## Scopes

Today **every API key has full access** to every endpoint: the dashboard creates keys with no scopes assigned, and does not offer a way to pick them yet.

The scope model itself is already implemented in the API. Each endpoint declares its own — `orders:read`, `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. If a key had scopes assigned and were missing the one an endpoint requires, the request would get `403 Forbidden`:

```json 403 Forbidden theme={null}
{
  "type": "ForbiddenError",
  "detail": "Missing required scope: orders:read"
}
```

<Note>
  Until you can choose scopes, treat every key as a full-access credential: create one per integration and delete it when you stop using it.
</Note>

## 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. Since keys are created without scopes today, you should not see this in practice |

```json 401 Unauthorized theme={null}
{
  "type": "UnauthorizedError",
  "detail": "Invalid or missing API key"
}
```

## Best Practices

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

* **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.