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.

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.

Both responses use the standard error envelope:

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

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.

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

What You Need#

Making an Authenticated Request#

When Authentication Fails#

What You Need

Making an Authenticated Request

When Authentication Fails