Create API Key

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

Show API Key Object

string

Unique identifier for the API key (e.g., “key_abc123”)

name

string

Human-readable name of the API key

key

string

The full API key string (format: prefix-secret)

prefix

string

First 8 characters of the API key for identification

permissions

array

Array of permissions granted to this key

isActive

boolean

Whether the API key is currently active

createdAt

string

ISO 8601 timestamp when the key was created

expiresAt

string

ISO 8601 timestamp when the key expires (null if no expiration)

usageCount

number

Number of requests made with this key (starts at 0)

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

Lead Permissions

leads:read - Read lead data and search leads - leads:write - Create, update, and delete leads - leads:enrich - Enrich lead data with external sources

User Permissions

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

Store Keys Securely

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

# Never commit to version control
echo "BUENA_API_KEY=abc12345-xyz789..." >> .env
echo ".env" >> .gitignore

Principle of Least Privilege

Only grant the minimum permissions needed:

// ❌ Too broad
permissions: ["*"]

// ✅ Specific to use case
permissions: ["linkedin:schedule", "leads:read"]

Regular Rotation

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

Monitor Usage

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

API Reference

Authentication

LinkedIn Automation

Voice Cloning

Lead Management

Enrichment & Prospecting

Campaigns & Users

SDK API Reference

Request

Body Parameters

Response

Available Permissions

Common Permission Sets

Read-Only Access

LinkedIn Automation

Full Lead Management

Complete Integration

Use Cases & Examples

1. Development Environment Key

2. Production Integration Key

3. Team Member Key

4. Temporary Integration Key

Security Best Practices

Error Responses

Invalid Permissions (400)

Insufficient Permissions (403)

Rate Limited (429)

Next Steps

Test Your Key

List All Keys

Start Automating

Best Practices

API Reference

Authentication

LinkedIn Automation

Voice Cloning

Lead Management

Enrichment & Prospecting

Campaigns & Users

SDK API Reference

​Request

​Body Parameters

​Response

​Available Permissions

​Common Permission Sets

​Read-Only Access

​LinkedIn Automation

​Full Lead Management

​Complete Integration

​Use Cases & Examples

​1. Development Environment Key

​2. Production Integration Key

​3. Team Member Key

​4. Temporary Integration Key

​Security Best Practices

​Error Responses

​Invalid Permissions (400)

​Insufficient Permissions (403)

​Rate Limited (429)

​Next Steps

Test Your Key

List All Keys

Start Automating

Best Practices

Request

Body Parameters

Response

Available Permissions

Common Permission Sets

Read-Only Access

LinkedIn Automation

Full Lead Management

Complete Integration

Use Cases & Examples

1. Development Environment Key

2. Production Integration Key

3. Team Member Key

4. Temporary Integration Key

Security Best Practices

Error Responses

Invalid Permissions (400)

Insufficient Permissions (403)

Rate Limited (429)

Next Steps