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."
}

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

​
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

​
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