API docs
Book a demo

General

Authentication

Page

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.


Making an Authenticated Request

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

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:

{
  "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.


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