# Authentication

Every request to the v2 API is authenticated with a project API key and scoped to a single project. You provide both on every call: the key proves who you are, and the project header tells the API which project's content you are working with.

## What You Need

Each request must include two things:

- **A project API key** in the `Authorization` header, using the Bearer scheme. Project keys are prefixed with `proj_`.
- **The `X-Project-ID` header**, set to the UUID of the project the request applies to.

Both are required on every endpoint. The key and the project must belong together -- a key can only access the project it was issued for.

> **Warning**
>
> **Keep your API key secret**
>
> Treat your project API key like a password. Never commit it to version control, never expose it in client-side code, and store it in an environment variable or a secret manager. Rotate it if you suspect it has been compromised.

---

## Making an Authenticated Request

Send both headers with every call. The example below retrieves a single enriched hotel.

```bash
curl -X POST https://api.ygo.ai/v2/project/content/getEnrichedHotel \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Project-ID: 0192fb17-5dc6-7abc-8def-123456789abc" \
  -H "Content-Type: application/json" \
  -d '{
    "HotelID": "01944a34-af9e-7d72-b7de-d2f29f3f77c1"
  }'
```

---

## When Authentication Fails

The API distinguishes between not knowing who you are and not letting you do something.

- **`401 Unauthorized`** -- The `Authorization` header is missing, malformed (for example, missing the `Bearer ` prefix), or the key is invalid or revoked.
- **`403 Forbidden`** -- The key is valid but is not allowed to act on the project in the request. This happens when `X-Project-ID` is missing, or when the key and the project do not belong together.
- **`403 Forbidden`** with the code `INSUFFICIENT_SCOPE` -- The key is valid for the project but does not carry the permission the endpoint requires. The `Message` names the missing permission, for example `token lacks scope content.generation:write`.

All of these responses use the standard error envelope:

```json
{
  "Error": {
    "Code": "UNAUTHORIZED",
    "Message": "Invalid API key"
  }
}
```

---

## Key Permissions

An API key can be issued with a permission set that limits which endpoints it may call. Permissions are named `product:access`, for example `content.catalog:read` or `content.generation:write`. A key issued without a permission set is unrestricted and may call every endpoint it has project access to.

Ask your account manager for a key restricted to the permissions your integration actually needs -- a read-only key for a catalog sync, for instance. Calls outside the key's permission set are refused with `403` and the code `INSUFFICIENT_SCOPE`.

---

> **Tip**
>
> **Both headers, every request**
>
> A common first-call mistake is sending the `Authorization` header but forgetting `X-Project-ID`. If a valid key returns `403`, check that the project header is present and matches the project your key was issued for, and read the `Code`: `INSUFFICIENT_SCOPE` means the project is fine and the key is missing a permission.

Need help? Reach our integration team at `integrations@ygo.ai`.
