Authentication - Buena.ai API

All Buena.ai API requests require authentication using user-specific API keys. Each key has granular permissions and tracks usage for security and billing purposes.

API Key Format

Buena.ai supports two types of API keys for maximum flexibility and backward compatibility:

User-Specific API Keys (Recommended)

Format: bna_[hexadecimal] where the hexadecimal string is 64 characters long:

bna_bxxxxxxxxxx

Benefits:

Automatic User Detection: No need to specify user IDs in requests
Enhanced Security: User-specific permissions and rate limiting
Better Tracking: Automatic usage tracking and last-used timestamps
Granular Permissions: Support for specific permission scopes

Global API Keys (Legacy)

Format: Traditional API key format for backward compatibility:

abc12345-xyz789def456ghi123jkl

Characteristics:

Full Access: All permissions (*)
Legacy Support: Works with all existing endpoints
Requires User IDs: Must specify user IDs in request parameters
Backward Compatible: Maintains compatibility with v1 API patterns

Authentication Header

Include your API key in the x-api-key header for all requests:

curl -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     "https://api.buena.ai/api/v2/health"

Never expose your API key in client-side code, public repositories, or logs. Always use environment variables or secure secret management.

Permission System

Each API key has specific permissions that control access to different endpoints. User-specific API keys support granular permissions, while global API keys have all permissions (*).

User Permissions

users:read - Read user data and settings - users:write - Modify user data and settings

LinkedIn Permissions

linkedin:schedule - Schedule LinkedIn actions - linkedin:upload - Upload prospect lists - linkedin:read - Read LinkedIn data - linkedin:voice - Send LinkedIn voice messages

Lead Permissions

leads:read - Read lead data - leads:write - Create/update leads - leads:enrich - Enrich lead data

Voice Permissions

voice:create - Create voice clones - voice:read - List voice clones - voice:update - Update voice settings - voice:delete - Delete voice clones - voice:preview - Generate voice previews

Job Permissions

jobs:read - Read job data and status - jobs:update - Modify job messages

Common Permission Sets

Read-Only Access

Perfect for analytics and monitoring: ["users:read", "linkedin:read", "leads:read", "jobs:read"]

LinkedIn Automation

For LinkedIn automation workflows: ["users:read", "linkedin:schedule", "linkedin:read", "jobs:read"]

Lead Management

For CRM integration and lead processing: ["users:read", "leads:read", "leads:write", "leads:enrich"]

Full Integration

For comprehensive platform integration:

["users:read", "users:write",         "linkedin:schedule", "linkedin:read", "leads:read", "leads:write",         "leads:enrich", "jobs:read"]

Permission Requirements by Endpoint

Endpoint	Permission Required
`POST /linkedin/scheduleLinkedInAction`	`linkedin:schedule`
`POST /linkedin/uploadProspects`	`linkedin:upload`
`GET /leads`	`leads:read`
`POST /leads`	`leads:write`
`POST /enrich`	`leads:enrich`
`GET /users/jobs`	`users:read`
`GET /health`, `GET /info`	None

Creating API Keys

Via Dashboard

Log into your Buena.ai dashboard
Navigate to Settings → API Keys
Click “Create New Key”
Set permissions and expiration
Copy and store the key securely

Via API

curl -X POST "https://api.buena.ai/api/v2/keys" \
  -H "x-api-key: YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "permissions": ["linkedin:schedule", "leads:read", "leads:write"],
    "expiresInDays": 365
  }'

const response = await fetch("https://api.buena.ai/api/v2/keys", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_EXISTING_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Integration",
    permissions: ["linkedin:schedule", "leads:read", "leads:write"],
    expiresInDays: 365,
  }),
});

import requests

response = requests.post(
    'https://api.buena.ai/api/v2/keys',
    headers={
        'x-api-key': 'YOUR_EXISTING_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Production Integration',
        'permissions': ['linkedin:schedule', 'leads:read', 'leads:write'],
        'expiresInDays': 365
    }
)

Managing API Keys

List Keys

curl -H "x-api-key: YOUR_API_KEY" \
     "https://api.buena.ai/api/v2/keys"

Update Key

curl -X PUT "https://api.buena.ai/api/v2/keys/{keyId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Key Name",
    "permissions": ["linkedin:read", "leads:read"]
  }'

Regenerate Key

curl -X POST "https://api.buena.ai/api/v2/keys/{keyId}/regenerate" \
  -H "x-api-key: YOUR_API_KEY"

Delete Key

curl -X DELETE "https://api.buena.ai/api/v2/keys/{keyId}" \
  -H "x-api-key: YOUR_API_KEY"

Best Practices

Environment Variables

Store API keys in environment variables, never in code:

export BUENA_API_KEY="your-api-key-here"

const apiKey = process.env.BUENA_API_KEY;

Key Rotation

Rotate keys every 90 days - Use different keys for different environments - Monitor key usage regularly - Deactivate unused keys immediately

Principle of Least Privilege

Only grant the minimum permissions needed: - Read-only operations: Use leads:read, linkedin:read - Automation scripts: Add linkedin:schedule, linkedin:upload - Full integration: Include leads:write, leads:enrich

Error Handling

Always check for authentication errors:

if (response.status === 401) {
  console.error('Invalid API key');
} else if (response.status === 403) {
  console.error('Insufficient permissions');
}

Authentication Errors

401 Unauthorized

{
  "error": true,
  "code": "UNAUTHORIZED",
  "message": "Invalid API key",
  "version": "2.0"
}

Causes:

Missing x-api-key header
Invalid API key format
Expired API key
Deactivated API key

403 Forbidden

{
  "error": true,
  "code": "PERMISSION_DENIED",
  "message": "Insufficient permissions",
  "version": "2.0",
  "permissionHelp": {
    "required": "linkedin:schedule",
    "available": ["linkedin:read"],
    "documentation": "https://docs.buena.ai/authentication"
  }
}

Causes:

API key lacks required permission
Attempting to access restricted endpoint
Rate limit exceeded

Testing Authentication

Use the health endpoint to verify your authentication:

curl -H "x-api-key: YOUR_API_KEY" \
     "https://api.buena.ai/api/v2/health"

const response = await fetch("https://api.buena.ai/api/v2/health", {
  headers: { "x-api-key": "YOUR_API_KEY" },
});

if (response.ok) {
  console.log("Authentication successful!");
} else {
  console.error("Authentication failed:", response.status);
}

Successful response:

{
  "version": "2.0",
  "status": "healthy",
  "authentication": "user",
  "user": {
    "id": "user_abc123",
    "email": "john@company.com",
    "role": "Premium"
  },
  "apiKey": {
    "name": "My Integration Key",
    "permissions": ["linkedin:schedule", "leads:read"],
    "usageCount": 42
  }
}

​API Key Format

​User-Specific API Keys (Recommended)

​Global API Keys (Legacy)

​Authentication Header

​Permission System

User Permissions

LinkedIn Permissions

Lead Permissions

Voice Permissions

Job Permissions

​Common Permission Sets

​Permission Requirements by Endpoint

​Creating API Keys

​Via Dashboard

​Via API

​Managing API Keys

​List Keys

​Update Key

​Regenerate Key

​Delete Key

​Best Practices

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Testing Authentication

API Key Format

User-Specific API Keys (Recommended)

Global API Keys (Legacy)

Authentication Header

Permission System

Common Permission Sets

Permission Requirements by Endpoint

Creating API Keys

Via Dashboard

Via API

Managing API Keys

List Keys

Update Key

Regenerate Key

Delete Key

Best Practices

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication