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

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

Security Note: Your API key is shown only once. Store it in a secure location immediately after generation.

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:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://api.zaits.net/v1/face/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -F "[email protected]" \
  -F "[email protected]"

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

Tip: IP whitelisting is recommended for production applications with static server IPs.

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:

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

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

# 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

{
  "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:

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

Success Response (200 OK):

{
  "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

Important: Always test the new key before deleting the old one to avoid service disruption.

Webhook Authentication

Webhooks use a different authentication method with HMAC signatures. See the Webhook Security section for details.

---

Next Steps:

• Quick Start Guide - Make your first API call

• SDK Installation - Use our official libraries

• Best Practices - Security and optimization tips