# CartAI authentication

CartAI authenticates API requests with an API key in a request header. There is a single API base URL for testing and live use.

## Base URL

From the OpenAPI `servers` entry:

```
https://api.cartai.ai
```

Source: https://docs.cartai.ai/openapi/latest.yml

## Header

Every request to the API must include the API key header. The Getting Started guide specifies this exact header:

```
X-API-Key: <your_api_key>
```

Source: https://docs.cartai.ai/reference/getting-started-with-ease

The OpenAPI marks the header as required on every operation. The published header name is not identical on every path:

- `X-Api-Key` on `POST /checkout` and `GET /checkout/{taskId}`
- `x-api-key` on the Catalog endpoints, checkout cancel, status history, interactive inputs, payment, and credential vault operations

Use `X-API-Key` to match Getting Started. That guide states that the header name is case-sensitive, and that a `401` can occur if the name is not exactly `X-API-Key`.

Send the key from your backend or a secrets manager. Do not put it in client-side code, commit it to source control, or share it publicly.

## Missing or invalid key

Getting Started documents these responses:

`401 Unauthorized` when the key is missing, malformed, or has been revoked:

```
{
  "error": "unauthorized",
  "message": "Missing or invalid API key. Include your key as the X-API-Key header."
}
```

`403 Forbidden` when the key is valid but does not have permission for the resource.

If you receive a `401`, confirm the header name and that the key has not been revoked in the portal.

## How to get an API key

Free tier: every new account gets 5 free credits, enough for 500 Catalog API calls.

The Getting Started guide is the official path:

1. Create an account at https://portal.cartai.ai/signup. Fill in your name, email, and a password. You will land in the CartAI portal.
2. Once you are logged in, open the API Keys section in the left sidebar.
3. Click Generate New Key.
4. Copy the key and store it somewhere safe.

If a key is compromised, return to the portal, revoke it, and generate a new one.

Sign in: https://portal.cartai.ai/login

The website also links to the same portal from https://www.cartai.ai/contact. If you cannot reach the signup page, use the contact page and request API access.

The Create Payment Session reference also says to generate a key from the CartAI Admin Portal after your account is provisioned, and to contact the CartAI Account Management Team to request access when needed: https://docs.cartai.ai/reference/create_payment_session

Getting Started notes that CartAI uses one environment for testing and going live, with simulated transactions during development, and that you should not use real card details while testing. When you are ready to go live, request access from the CartAI Dashboard using the "Request Go Live" button, as described in that guide.

## Related resources

- Agent guide: https://www.cartai.ai/agents.md
- API reference: https://docs.cartai.ai/reference/
- Getting Started: https://docs.cartai.ai/reference/getting-started-with-ease
- OpenAPI: https://docs.cartai.ai/openapi/latest.yml
- Contact: https://www.cartai.ai/contact
