> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trywildcard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Wildcard API

The visitor-data API uses a **data key** (`mk_live_...`) in the `X-API-Key` header.
`GET /v1/health` is public and needs no key.

Partner provisioning uses a separate **management key** (`pk_live_...`) on
`/v1/partner/domains`, `/v1/partner/domain-groups`, and `/v1/partner/api-keys`.
Get that key from [Partner Dashboard](https://app.maverickintelligence.co/partner/dashboard)
→ **Domain Management API Key**. It belongs to your Wildcard partner account;
store it in your own application's backend secrets. It cannot read `/v1/people`.

| Request | Key |
| - | - |
| Register sites or manage groups at `/v1/partner/*` | `pk_live_...` |
| Read visitors and events at `/v1/people` and `/v1/people/{id}/events` | `mk_live_...` |
| Check `/v1/health` | No key |

See [Partners](https://docs.trywildcard.ai/partners.md) for the complete site-builder workflow.

```bash theme={null}
curl -H "X-API-Key: mk_live_a1b2c3d4e5f6..." \
  https://api-v1.maverickintelligence.co/v1/people
```

## Getting an API key

1. Log in to your [Wildcard dashboard](https://app.maverickintelligence.co)
2. Open **Integrations** from the sidebar
3. Find the **Developer API** card and click **Manage Keys**
4. Click **Create API Key**
5. Copy the key immediately — it's only shown once

## Data key format

Data keys follow the format `mk_live_` followed by 40 random hex characters:

```
mk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
```

## Security best practices

* **Never expose keys in client-side code** — use your API key from a backend server only
* **Store keys securely** — use environment variables or a secrets manager
* **Rotate keys regularly** — you can have up to 5 active keys at a time
* **Revoke compromised keys immediately** — revocation is instant

## Data key limits

* Maximum **5 active keys** per account
* Keys can be revoked instantly from the dashboard
* All keys share the same rate limit pool (1,000 requests/hour)

## Domain-scoped keys

Partner accounts can issue keys restricted to a single tracked client domain, so
one client's key cannot read another client's visitors. These keys sit outside the
5-key limit and each carries its own rate limit pool rather than sharing yours.

See [Partners](https://docs.trywildcard.ai/partners.md) for how to issue them.

## Error responses

| Status | Code | Description |
| - | - | - |
| 401 | `unauthorized` | Missing API key (header not provided) |
| 403 | `forbidden` | Invalid or revoked API key |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.