# Authentication

Learn how to authenticate your API requests and manage your API keys securely.

## Overview

All Zaits API requests require authentication using API keys. Your API keys carry many privileges, so be sure to keep them secure and never share them in publicly accessible areas.

## Getting Your API Key

1. **Sign up** for a Zaits account at [zaits.net](https://zaits.net)
2. **Navigate** to the "API Keys" section in your dashboard
3. **Click** "Generate New API Key"
4. **Copy** your API key and store it securely

{% hint style="warning" %}
**Security Note:** Your API key is shown only once. Store it in a secure location immediately after generation.
{% endhint %}

## API Key Types

### API Key Format

All API keys follow this format:

```
sk_1234567890abcdef1234567890abcdef
```

## Making Authenticated Requests

Include your API key in the `Authorization` header using the `Bearer` authentication scheme:

```http
Authorization: Bearer YOUR_API_KEY
```

### Example Request

```bash
curl -X POST https://api.zaits.net/v1/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -F "image1=@face1.jpg" \
  -F "image2=@face2.jpg"
```

## Permissions

API keys have different permission levels that control what operations they can perform:

### Permission Types

| Permission | Description                                 | Endpoints                                  |
| ---------- | ------------------------------------------- | ------------------------------------------ |
| **Read**   | Access to GET operations and data retrieval | `/v1/usage/*`, `/v1/webhooks/events`       |
| **Write**  | Access to POST, PUT, DELETE operations      | `/v1/face/*`, `/v1/ocr/*`, `/v1/signing/*` |

### Checking Permissions

You can view and modify permissions for your API keys in the dashboard under "API Keys" → "Permissions".

## IP Whitelisting

For additional security, you can restrict API key usage to specific IP addresses:

1. **Go to** your API Keys page in the dashboard
2. **Click** on the API key you want to restrict
3. **Add** allowed IP addresses in the "IP Whitelist" section
4. **Save** your changes

{% hint style="info" %}
**Tip:** IP whitelisting is recommended for production applications with static server IPs.
{% endhint %}

### IP Format Examples

```
192.168.1.1        # Single IP
192.168.1.0/24     # IP range (CIDR notation)
203.0.113.0/24     # Another IP range
```

## Security Best Practices

### Do's

* **Store API keys securely** in environment variables
* **Use different keys** for development and production
* **Rotate keys regularly** (every 90 days recommended)
* **Monitor API key usage** in your dashboard
* **Use IP whitelisting** for production applications

### Don'ts

* **Never commit API keys** to version control
* **Don't share API keys** in public forums or chat
* **Don't use live keys** in client-side code
* **Don't use the same key** across multiple applications

### Environment Variables

Store your API key in environment variables:

```bash
# .env file
ZAITS_API_KEY=YOUR_API_KEY
ZAITS_API_URL=https://api.zaits.net
```

```javascript
// JavaScript/Node.js
const apiKey = process.env.ZAITS_API_KEY;
```

```python
# Python
import os
api_key = os.getenv('ZAITS_API_KEY')
```

## Authentication Errors

### Common Authentication Issues

| Error Code                 | HTTP Status | Description                        | Solution                                 |
| -------------------------- | ----------- | ---------------------------------- | ---------------------------------------- |
| `missing_api_key`          | 401         | No API key provided                | Include `Authorization` header           |
| `invalid_api_key`          | 401         | API key is invalid or expired      | Check your API key is correct            |
| `insufficient_permissions` | 403         | API key lacks required permissions | Enable required permissions in dashboard |
| `ip_not_allowed`           | 403         | Request from non-whitelisted IP    | Add your IP to the whitelist             |

### Example Error Response

```json
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has expired",
    "details": {
      "key_prefix": "sk_1234..."
    }
  }
}
```

## Testing Your Authentication

Test your API key with a simple request:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.zaits.net/v1/usage/summary
```

**Success Response (200 OK):**

```json
{
  "success": true,
  "data": {
    "credits": {
      "remaining": 1000,
      "total_purchased": 1000
    }
  }
}
```

## Managing Multiple API Keys

You can create multiple API keys for different purposes:

* **Production App**: Live key with write permissions
* **Staging Environment**: Staging key with write permissions
* **Analytics Service**: Live key with read-only permissions
* **Mobile App**: Live key with limited permissions

## Key Rotation

Regular key rotation improves security:

1. **Generate** a new API key in the dashboard
2. **Update** your application with the new key
3. **Test** that everything works correctly
4. **Delete** the old API key

{% hint style="warning" %}
**Important:** Always test the new key before deleting the old one to avoid service disruption.
{% endhint %}

## Webhook Authentication

Webhooks use a different authentication method with HMAC signatures. See the [Webhook Security](/api/api-reference/webhooks.md#webhook-security) section for details.

***

**Next Steps:**

* [Quick Start Guide](/api/getting-started/quickstart.md) - Make your first API call
* [SDK Installation](https://github.com/ZaitsLLC/platform/blob/master/docs/sdks/overview.md) - Use our official libraries
* [Best Practices](/api/guides/best-practices.md) - Security and optimization tips


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://zaits.gitbook.io/api/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.