Skip to main content
POST
/
api
/
v2
/
keys
Create API Key
curl --request POST \
  --url https://api.buena.ai/api/v2/keys \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "permissions": [
    {}
  ],
  "expiresInDays": 123
}
'
{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "Production Integration",
    "key": "abc12345-xyz789def456ghi123jkl456mno789pqr",
    "prefix": "abc12345",
    "permissions": [
      "linkedin:schedule",
      "linkedin:upload",
      "leads:read",
      "leads:write"
    ],
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2025-01-15T10:30:00Z",
    "usageCount": 0
  },
  "message": "API key created successfully. Please store the key securely as it won't be shown again."
}

Documentation Index

Fetch the complete documentation index at: https://docs.buena.ai/llms.txt

Use this file to discover all available pages before exploring further.

Create a new API key for your account with granular permissions and optional expiration. This endpoint allows you to generate API keys programmatically for different use cases and team members.
You need an existing API key to create new ones. If you don’t have any API keys yet, create your first one through the Buena.ai dashboard.

​
Request

​
x-api-key
string
required
Your existing API key for authentication
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
name
string
required
Human-readable name for the API key (e.g., “Production Integration”, “Development Key”)
​
permissions
array
default:"[]"
Array of permissions to grant to this API key. See permission reference.
​
expiresInDays
number
default:"365"
Number of days until the API key expires (1-365 days). Set to 0 for no expiration.
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", "linkedin:upload", "leads:read", "leads:write"],
    "expiresInDays": 365
  }'

​
Response

​
success
boolean
Always true for successful requests
​
data
object
The created API key information
​
message
string
Success message with security reminder
{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "Production Integration",
    "key": "abc12345-xyz789def456ghi123jkl456mno789pqr",
    "prefix": "abc12345",
    "permissions": [
      "linkedin:schedule",
      "linkedin:upload",
      "leads:read",
      "leads:write"
    ],
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2025-01-15T10:30:00Z",
    "usageCount": 0
  },
  "message": "API key created successfully. Please store the key securely as it won't be shown again."
}

​
Available Permissions

  • linkedin:schedule - Schedule LinkedIn actions (connection requests, messages) - linkedin:upload - Upload prospect lists for automation campaigns - linkedin:read - Read LinkedIn data and integration status
  • leads:read - Read lead data and search leads - leads:write - Create, update, and delete leads - leads:enrich - Enrich lead data with external sources
  • users:read - Read user data and team information - admin - Full administrative access to account

​
Common Permission Sets

Here are some common permission combinations for different use cases:

​
Read-Only Access

{
  "permissions": ["linkedin:read", "leads:read", "users:read"]
}

​
LinkedIn Automation

{
  "permissions": ["linkedin:schedule", "linkedin:upload", "linkedin:read"]
}

​
Full Lead Management

{
  "permissions": ["leads:read", "leads:write", "leads:enrich"]
}

​
Complete Integration

{
  "permissions": [
    "linkedin:schedule",
    "linkedin:upload",
    "linkedin:read",
    "leads:read",
    "leads:write",
    "leads:enrich",
    "users:read"
  ]
}

​
Use Cases & Examples

​
1. Development Environment Key

Create a key for development with read-only permissions: 
const devKey = await createAPIKey({
  name: "Development Environment",
  permissions: ["linkedin:read", "leads:read"],
  expiresInDays: 30,
});

​
2. Production Integration Key

Create a key for production with full permissions: 
const prodKey = await createAPIKey({
  name: "Production - LinkedIn Automation",
  permissions: [
    "linkedin:schedule",
    "linkedin:upload",
    "linkedin:read",
    "leads:read",
    "leads:write",
    "leads:enrich",
  ],
  expiresInDays: 365,
});

​
3. Team Member Key

Create a restricted key for a team member: 
const teamKey = await createAPIKey({
  name: "John Smith - Analytics",
  permissions: ["leads:read", "users:read"],
  expiresInDays: 90,
});

​
4. Temporary Integration Key

Create a short-lived key for testing: 
const tempKey = await createAPIKey({
  name: "Temporary Testing Key",
  permissions: ["linkedin:read", "leads:read"],
  expiresInDays: 7,
});

​
Security Best Practices

# Use environment variables
export BUENA_API_KEY="abc12345-xyz789..."

# Never commit to version control
echo "BUENA_API_KEY=abc12345-xyz789..." >> .env
echo ".env" >> .gitignore
Only grant the minimum permissions needed:
// ❌ Too broad
permissions: ["*"]

// ✅ Specific to use case
permissions: ["linkedin:schedule", "leads:read"]
Rotate keys regularly, especially for production:
// Rotate every 90 days
const newKey = await createAPIKey({
  name: "Production Key - Q1 2024",
  permissions: existingPermissions,
  expiresInDays: 90
});

// Update your application configuration
// Deactivate old key after transition
Track API key usage for security monitoring:
// Check usage periodically
const keys = await listAPIKeys();
keys.forEach(key => {
  if (key.usageCount === 0 && isOlderThan(key.createdAt, 30)) {
    console.warn(`Unused key: ${key.name}`);
  }
});

​
Error Responses

​
Invalid Permissions (400)

{
  "error": true,
  "code": "VALIDATION_ERROR",
  "message": "Invalid permission specified",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z",
  "details": {
    "invalidPermissions": ["invalid:permission"],
    "validPermissions": [
      "linkedin:schedule",
      "linkedin:upload",
      "linkedin:read",
      "leads:read",
      "leads:write",
      "leads:enrich",
      "users:read"
    ]
  }
}

​
Insufficient Permissions (403)

{
  "error": true,
  "code": "PERMISSION_DENIED",
  "message": "Cannot create API key with higher permissions than your own",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z",
  "details": {
    "yourPermissions": ["linkedin:read", "leads:read"],
    "requestedPermissions": ["admin"]
  }
}

​
Rate Limited (429)

{
  "error": true,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many API key creation requests",
  "version": "2.0",
  "timestamp": "2024-01-20T15:30:00Z",
  "retryAfter": 300
}
Important Security Note: The full API key is only returned once during creation. Store it immediately in a secure location. If you lose the key, you’ll need to regenerate it or create a new one.

​
Next Steps

After creating your API key:

Test Your Key

Verify your new key works with a health check

List All Keys

View all your API keys and their permissions

Start Automating

Begin LinkedIn automation with your new key

Best Practices

Learn security best practices for API keys