Authentication

Ayra API uses API key authentication where each request must include a valid API key in the request headers. When you make an API request, you include your API key in the Authorization header using Bearer token format.

How Authentication Works

The API validates your key and determines which resources you can access based on the key's permissions.

Authentication happens on every request. There's no concept of "logging in" and maintaining session state. Each request is independently authenticated using the provided API key. This stateless authentication model is simple, secure, and scales well.

Authentication Header Format

Include your API key in the Authorization header of every request using this format:

Authorization: Bearer YOUR_API_KEY_HERE

Example cURL Request:

curl https://api.ayra.ai/v1/agents \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json"

Example in JavaScript (Node.js):

const axios = require('axios');

const response = await axios.get('https://api.ayra.ai/v1/agents', {
  headers: {
    'Authorization': 'Bearer sk_live_abc123xyz789',
    'Content-Type': 'application/json'
  }
});

Example in Python:

import requests

headers = {
    'Authorization': 'Bearer sk_live_abc123xyz789',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.ayra.ai/v1/agents', headers=headers)

Example in PHP:

<?php
$api_key = 'sk_live_abc123xyz789';

$ch = curl_init('https://api.ayra.ai/v1/agents');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $api_key,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

Authentication Errors

When authentication fails, the API returns specific error codes helping diagnose the issue:

{
  "error": {
    "type": "authentication_error",
    "message": "No API key provided",
    "code": "missing_api_key"
  }
}

{
  "error": {
    "type": "authentication_error", 
    "message": "Invalid API key provided",
    "code": "invalid_api_key"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "API key has expired",
    "code": "expired_api_key"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "API key has been revoked",
    "code": "revoked_api_key"
  }
}

{
  "error": {
    "type": "permission_error",
    "message": "This API key lacks permission to perform this action",
    "code": "insufficient_permissions",
    "required_permission": "agents:write"
  }
}

Testing Authentication

To verify authentication is working correctly, call the API info endpoint:

curl https://api.ayra.ai/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful authentication returns your account details:

{
  "data": {
    "account_id": "acc_abc123",
    "email": "you@company.com",
    "company_name": "Your Company",
    "plan": "professional",
    "api_version": "v1"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Failed authentication returns 401 error as described above.

Security Best Practices

// Good - using environment variable
const apiKey = process.env.AYRA_API_KEY;

// Bad - hardcoded key
const apiKey = 'sk_live_abc123xyz789';