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

# Asva AI API: Authentication with Bearer API Keys

> Secure your Asva AI API calls with Bearer token authentication — how to get a key, pass it correctly, handle errors, and stay within rate limits.

Every request to the Asva AI API must be authenticated. Authentication uses API keys issued per workspace — there are no per-user keys, no OAuth flows, and no session cookies. You pass your key as a `Bearer` token in the `Authorization` header on every request. The API validates the key, checks your rate limit, and then processes your request.

## Get an API key

API keys are issued per workspace. To get yours:

1. Visit [asva-ai.com/get-help](https://asva-ai.com/get-help) and book a call
2. Or email [hello@asva-ai.com](mailto:hello@asva-ai.com) with the subject line "API Access"

Your key will arrive in the format `asva_live_...`

<Warning>
  Keep your API key secret. Never commit it to version control or expose it in client-side JavaScript. Store it as an environment variable and access it server-side only.
</Warning>

***

## Pass your API key

Include your key as a `Bearer` token in the `Authorization` header on every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://asva-ai.com/api/audit \
    -H "Authorization: Bearer $ASVA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"domain": "yourstore.com"}'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://asva-ai.com/api/audit', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ASVA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'yourstore.com' })
  })
  ```

  ```python Python theme={null}
  import os
  import requests

  headers = {
      'Authorization': f'Bearer {os.environ["ASVA_API_KEY"]}',
      'Content-Type': 'application/json'
  }

  response = requests.post(
      'https://asva-ai.com/api/audit',
      headers=headers,
      json={'domain': 'yourstore.com'}
  )
  ```
</CodeGroup>

***

## Base URL

All API endpoints use:

```
https://asva-ai.com/api
```

There is no separate staging or sandbox URL. To test without side effects, pass `dry_run: true` in the request body — the API returns a valid response using cached data without re-fetching or writing anything.

***

## Error responses

| Status | Error code     | Description                                             |
| ------ | -------------- | ------------------------------------------------------- |
| `401`  | `unauthorized` | Missing or invalid API key                              |
| `403`  | `forbidden`    | API key is valid but lacks permission for this resource |
| `429`  | `rate_limited` | Too many requests — see rate limits below               |

**401 response example:**

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Pass your key as: Authorization: Bearer asva_live_..."
  }
}
```

***

## Rate limits

| Endpoint             | Limit                 |
| -------------------- | --------------------- |
| `POST /api/audit`    | 60 requests / hour    |
| `POST /api/manifest` | 100 requests / hour   |
| `POST /api/report`   | 1,000 requests / hour |

Rate limit headers are returned on every response:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1744281600
```

`X-RateLimit-Reset` is a Unix timestamp. Wait until that time before retrying after a `429`. If you are running batch jobs (for example, auditing multiple client domains), spread requests across the hour rather than bursting all at once.

<Tip>
  If you need higher rate limits for agency batch workflows, mention it when you book your onboarding call.
</Tip>

***

## SDK

TypeScript and Python SDKs are in development. Until they are available, use the REST API directly with the examples above.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Readiness API" icon="gauge" href="/api-reference/readiness">
    Run a readiness audit against any domain.
  </Card>

  <Card title="Manifest API" icon="wand-magic-sparkles" href="/api-reference/manifest">
    Generate and validate UCP manifests.
  </Card>

  <Card title="Attribution API" icon="chart-line" href="/api-reference/attribution">
    Log events and pull attribution data.
  </Card>
</CardGroup>