# Authentication

## Authentication

### Overview

To interact with the Anvil API, you’ll need an **API Key**. Think of the API Key as your personal pass to our Cardano infrastructure—each key enforces daily usage limits and burst configurations tailored to your project’s needs.

**Important**: Treat your API Key like a password. If someone else gains access to it, they can use your quota and potentially access your resources.

***

### How to Get Your API Key

Visit our **self-serve portal** at [ada-anvil.io/api-keys](https://ada-anvil.io/api-keys) to generate your keys instantly. If the portal is unavailable, please email us at `hello@ada-anvil.io`.

***

## How to Use Your API Key

You will receive two API keys from Anvil:

* **Testnet Key**: Use this key for all non-production Cardano environments, including **Preprod** and **Preview**.
* **Mainnet Key**: Use this key exclusively for the Cardano **Mainnet** environment.

To authenticate your requests, include the appropriate key in the `X-Api-Key` header.

### Basic cURL Example

```bash
curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: YOUR_API_KEY_HERE" \
    https://prod.api.ada-anvil.app/v2/services/health
```

**Endpoint**: Replace with the environment you want to interact with (e.g., `preprod.api.ada-anvil.app`, `preview.api.ada-anvil.app`, etc.).

**Method**: Varies depending on the API call (GET, POST, etc.).

**Headers**: Always include your `X-Api-Key`.

### Basic NodeJS Example

```typescript
async function checkHealth() {
  try {
    const response = await fetch(
      "https://prod.api.ada-anvil.app/v2/services/health",
      {
        headers: {
          "X-Api-Key": "YOUR_API_KEY_HERE",
        },
      },
    );
    console.log("Health Check:", await response.json());
  } catch (error) {
    console.error("Error:", error);
  }
}

(async () => {
  await checkHealth();
})();
```

### Python (Requests) Example

```python
import requests

def check_health():
    url = "https://prod.api.ada-anvil.app/v2/services/health"
    headers = {
        "X-Api-Key": "YOUR_API_KEY_HERE",
        "Content-Type": "application/json"
    }

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        print("Health Check:", response.json())
    else:
        print("Error:", response.status_code, response.text)

check_health()
```

***

## Rate Limits and Quotas

Every API Key has **usage limits** that define:

* **Maximum requests per day**
* **Requests per second (RPS)**
* **Burst limits** for short-term high-traffic events

These are set during onboarding. If you anticipate large spikes, contact us to adjust your limits.

**Tip**: Exceeding your rate limits may result in 429 (Throttled, please try again later) errors. In such cases, either reduce your request frequency or upgrade your quota.

***

## Best Practices

1. **Store Keys Securely**

* Use environment variables or a secure key management service.
* Avoid committing keys to public Git repositories.

2. **Rotate Keys Periodically**

* If you suspect your key has been exposed, email us immediately for revocation and re-issuance.
* Regular key rotation is a good security measure.

3. **Use Separate Keys for Each Environment**

* Keep your Preprod and Mainnet usage separate for better debugging and resource tracking.

4. **Handle Errors Gracefully**

* Look for `401 Unauthorized` (invalid or missing API key) or `Throttled, please try again later.`.
* Implement retry logic with exponential backoff to avoid overwhelming the service.

***

## Common Troubleshooting

### `401 Unauthorized`

Check that you set the `X-Api-Key` header exactly as provided.

Confirm the key belongs to the specific environment you’re calling.

### `Throttled, please try again later.`

You may have hit your burst or daily limit. Throttle your requests or contact support for higher limits.

### `Incorrect Endpoint`

Verify you’re using the correct URL (Mainnet vs. Preprod vs. Preview). Refer to the Usage page for correct endpoints.

***

## Moving Forward

Once your key is active, you can start exploring all the functionality that **Anvil’s Cardano APIs** offer—everything from minting tokens to submitting transactions and checking balances. Need guidance on environment selection? Head back to our Usage page for a refresher.

**Next Steps:**

* Dive deeper into Select Cardano Environment to ensure you’re building on the right network for your needs.
* Explore UTXOs vs. Change Address to understand Cardano’s transaction model.
* Build your first transaction or NFT mint using our step-by-step guides in the sidebar.

With your **API Key** in hand and the right environment chosen, you’re ready to harness the power of Cardano through Anvil—securely and efficiently!