# auth.md

**Luigi's Box — agent authentication.**

This document tells automated agents how to obtain and use credentials for the
Luigi's Box API. Authoritative reference:
<https://docs.luigisbox.com/platform-foundations/api-principles/>.

## Summary

| | |
|---|---|
| **Scheme** | HMAC-SHA256 request signing (custom) |
| **OAuth 2.0 / OpenID Connect** | **Not offered.** Do not probe `/.well-known/openid-configuration`, `/.well-known/oauth-authorization-server` or `/.well-known/oauth-protected-resource` — those endpoints do not exist and will not be added while the API uses HMAC. |
| **Self-service agent registration** | Not available. Credentials are issued per account by Luigi's Box. |
| **Credential type** | Public identifier (`tracker_id`) plus a Secret Key for private endpoints |

## Two tiers of access

### Public API — no credentials beyond `tracker_id`

Search, Autocomplete, Recommender, Product Listing, Shopping Assistant, Top Items and
Trending Queries need only a `tracker_id` query parameter. No signature, no secret. The
`tracker_id` is public and safe to use in a browser.

```
GET https://live.luigisbox.com/search?tracker_id=<TRACKER_ID>&q=<QUERY>
```

An agent acting on behalf of a Luigi's Box customer can call these endpoints as soon as it
knows the customer's `tracker_id`.

### Private API — HMAC-SHA256 signature required

Catalog indexing, content management and the Analytics Events API require a signature
computed with the account's Secret Key.

Signing procedure:

1. Build a canonical string from the HTTP method, the `Content-Type` header, the `Date`
   header and the resource path.
2. Compute an HMAC-SHA256 digest of that string using the Secret Key.
3. Base64-encode the digest and send it in the `Authorization` header.

The exact canonical-string layout is documented at
<https://docs.luigisbox.com/platform-foundations/api-principles/>. Follow it precisely —
signatures are rejected on any mismatch, and a stale or mistimed `Date` header is the most
common cause of failure.

## How to obtain credentials

There is no programmatic registration endpoint. Credentials are issued to an account, not
to an agent:

1. An account is created at <https://app.luigisbox.com/> or through Luigi's Box sales.
2. The `tracker_id` and Secret Key are available in that dashboard.
3. For a new evaluation account, start at <https://www.luigisbox.com/pricing/> or contact
   <sales@luigisbox.com>.

An agent that needs Private API access must ask its human operator to supply the Secret
Key from the dashboard. Do not attempt to enrol, provision or self-issue credentials.

## Handling secrets

- The Secret Key is **server-side only**. Never place it in browser JavaScript, a mobile
  app bundle, a public repository, a URL query string or a log line.
- Treat the `tracker_id` as public; treat the Secret Key as a password.
- If a Secret Key is exposed, rotate it in the dashboard and notify
  <support@luigisbox.com>.

## Rate limits and errors

Rate limits and error semantics are documented with the API principles above. Back off on
`429` and `5xx` rather than retrying immediately.

## This website

`www.luigisbox.com` is a public marketing and documentation site. It requires no
authentication, and no part of it sits behind a paywall or token. Machine-readable
descriptions of what it offers:

- <https://www.luigisbox.com/llms.txt>
- <https://www.luigisbox.com/.well-known/ai-catalog.json>
- <https://www.luigisbox.com/.well-known/api-catalog>
- <https://www.luigisbox.com/.well-known/agent-skills/index.json>

## Contact

- Technical support: <support@luigisbox.com>
- Documentation: <https://docs.luigisbox.com/>
- Service status: <https://www.luigisboxstatus.com/>