Authentication #

Every API request must carry your API key so Your AI Connector knows it is you and which account to act on. You can send the key four different ways — all of them work on every endpoint that accepts API-key authentication, so pick whichever fits your setup.

API access is a paid feature. If your plan does not include it, requests are rejected with a 403 even when the key itself is valid — see The paid-feature gate below. To generate a key, see API Access.

HTTPS only. All requests must use a secure connection. Plain HTTP requests are rejected before authentication even runs.

The four methods at a glance #

When more than one is present, the query parameter wins, then the X-API-Key header, then the bearer token. In practice you only ever send one.

1. Query parameter — ?apiKey= #

Add your key to the end of the web address. This is the simplest form and always works, which makes it ideal for quick tests, scripts, and any older tooling.

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

Heads up: Web addresses end up in browser history, server access logs, and proxy logs. For anything beyond a quick test, prefer one of the header methods below so your key is not written to disk in plain sight.

2. X-API-Key header #

Send the key in a dedicated header. This keeps it out of the URL and is the recommended choice for production.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

3. Authorization: Bearer header #

You can also pass the key as a standard bearer token. This is handy when your HTTP client or framework already has built-in support for Authorization headers.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

The API tells your API key apart from a login token automatically, so this method works exactly like X-API-Key.

4. Firebase ID token (first-party only) #

If you are building a first-party app that signs users in through Your AI Connector's own login, you can pass that signed-in user’s Firebase ID token as a bearer token instead of an API key:

Authorization: Bearer <Firebase ID token>

The token is verified on every request and maps to the signed-in account. This method is only for first-party app sessions — you cannot mint these tokens from an external integration, and there is no way to obtain one without going through the normal app login. For server-to-server and third-party integrations, use an API key (methods 1–3).

When to use which #

• Quick tests and one-off scripts → query parameter (?apiKey=). Fastest to type, works in a browser.
• Production integrations and server-to-server calls → X-API-Key or Authorization: Bearer YOUR_API_KEY. Keeps the key out of URLs and logs.
• First-party apps with a logged-in Your AI Connector user → Authorization: Bearer <Firebase ID token>.

Key scopes #

Your account has one main API key — the one under Settings → Integrations → API Key. It has full access to everything the account can do.

You can also create extra scoped keys: named keys that only reach the parts of the API you choose, for example a read-only key limited to Analytics for a reporting dashboard. A scoped key is sent exactly like the main key (any of methods 1–3 above), but it is checked against its own permissions on every request:

• Outside its allowed areas it is refused. A write with a read-only key, or a call to a section the key was not given, comes back as 403 — key_read_only or key_scope_denied in the error_code field. The check is deliberately strict: anything that is not clearly inside the key’s allowed areas is refused rather than let through, so if you see one of those 403s, the key simply does not cover that endpoint.
• It has its own rate-limit budget. A scoped key is counted separately from your main key, so a busy dashboard on a scoped key cannot use up the allowance your other integrations depend on. You choose that per-minute budget when you create the key.
• It cannot manage API keys. Only the account owner — signed in, or using the main key — can list, create, edit, rotate or revoke keys. A scoped key can never mint itself a wider one.

See API Keys for how to create, edit and revoke scoped keys.

The paid-feature gate #

API access is a paid feature. When your plan does not include it, a request with an otherwise-valid key is rejected with 403:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

Keeping your key safe #

• Treat the key like a password. Your main key grants full access to your account. If you need to hand a key to a tool or a person who only needs part of it, create a scoped key instead — see Key scopes.
• Keep it server-side. Never embed it in browser JavaScript, a mobile app bundle, or any code an end user can read.
• Store it in a secret manager or server-side configuration, not in source control.
• Rotate it if it leaks. Generate a new key from the dashboard or call POST https://api.youraiconnector.com/v1/api-keys/rotate — this immediately invalidates the old one. See API Keys.
• Always use HTTPS so the key is encrypted in transit.

Next steps #

• Getting Started — your first request and the resource guides.
• Errors & Pagination — handle failures and page through results.
• API Keys — rotate, revoke, and check usage on your key.