General
Authentication
PageMore page actions
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
Authorizationheader, using the Bearer scheme. Project keys are prefixed withproj_. - The
X-Project-IDheader, 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– TheAuthorizationheader is missing, malformed (for example, missing theBearerprefix), 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 whenX-Project-IDis missing, or when the key and the project do not belong together.403 Forbiddenwith the codeINSUFFICIENT_SCOPE– The key is valid for the project but does not carry the permission the endpoint requires. TheMessagenames the missing permission, for exampletoken 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.
