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

# Authentication

> API key management, free vs paid modes, and security best practices.

All NAWA API requests require a Bearer token in the `Authorization` header.

```bash theme={null}
Authorization: Bearer nawa_live_sk_xxx
```

## API key formats

| Environment | Prefix          | Example                     |
| ----------- | --------------- | --------------------------- |
| Free        | `nawa_test_sk_` | `nawa_test_sk_a1b2c3d4e5f6` |
| Live        | `nawa_live_sk_` | `nawa_live_sk_x9y8z7w6v5u4` |

## Free vs live keys

<CardGroup cols={2}>
  <Card title="Free" icon="flask">
    **Free, no credit card required.**

    * 100 lifetime requests
    * 14-day key expiry
    * Uses real AI models (same accuracy)
    * Rate limit: 10 requests/minute
    * Perfect for prototyping and testing
  </Card>

  <Card title="Live" icon="rocket">
    **Pay-as-you-go with credit packs.**

    * Unlimited requests (with credits)
    * No key expiry (rotate at 90 days recommended)
    * Full rate limits by tier
    * Webhook support
    * Analytics and usage dashboards
  </Card>
</CardGroup>

## Creating API keys

<Steps>
  <Step title="Sign in to your account">
    Go to [trynawa.com/developers/keys](https://trynawa.com/developers/keys) and sign in with your account.
  </Step>

  <Step title="Create a new key">
    Go to [trynawa.com/developers/keys](https://trynawa.com/developers/keys) and click **Create Key**.
  </Step>

  <Step title="Copy your key">
    Your key is displayed **once** at creation. Copy it immediately and store it securely.

    <Warning>
      API keys are shown only once at creation. They are stored as SHA-256 hashes  -  we cannot retrieve your key later. If you lose it, revoke the old key and create a new one.
    </Warning>
  </Step>
</Steps>

## Key rotation

We recommend rotating live keys every **90 days**. To rotate without downtime:

1. Create a new key in the dashboard
2. Update your application to use the new key
3. Verify requests succeed with the new key
4. Revoke the old key

<Tip>
  You can have up to 5 active keys per environment. This allows zero-downtime rotation by running old and new keys simultaneously.
</Tip>

## Key revocation

Revoke a key instantly from the dashboard under **Settings → API Keys**. Revoked keys return a `401 authentication_error` immediately.

## Security best practices

* **Never commit keys to source control.** Use environment variables or a secret manager.
* **Use free keys for development.** Reserve live keys for deployed applications.
* **Restrict keys by IP** (planned) for live workloads.
* **Monitor usage** in the dashboard to detect unauthorized use.
* **Rotate keys** every 90 days or immediately if compromised.

```typescript theme={null}
// ✅ Load from environment
const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })

// ❌ Never hardcode keys
const nawa = new Nawa({ apiKey: 'nawa_live_sk_abc123' })
```