API keys
Create and manage API keys for authenticating with the Agentbot API. All endpoints require session authentication.
List keys
Response
{
"keys": [
{
"id": "key_123",
"name": "Production Key",
"keyPreview": "sk_abc1234...",
"createdAt": "2026-03-01T00:00:00Z",
"lastUsed": "2026-03-19T00:00:00Z"
}
]
}
Create key
Request body
| Field | Type | Required | Description |
|---|
name | string | Yes | Key name (max 64 characters) |
Response (201 Created)
{
"id": "key_456",
"name": "Production Key",
"key": "sk_a1b2c3d4e5f6...",
"createdAt": "2026-03-19T00:00:00Z"
}
The raw API key is only returned once at creation time. Store it securely — it cannot be retrieved again. The key is stored as a bcrypt hash in the database.
Errors
| Code | Description |
|---|
| 400 | Name required or name too long (max 64 characters) |
| 401 | Unauthorized |
| 500 | Failed to create key |
Get key
Requires ownership of the key.
Response
{
"id": "key_123",
"name": "Production Key",
"keyPreview": "sk_abc1234...",
"createdAt": "2026-03-01T00:00:00Z",
"lastUsed": "2026-03-19T00:00:00Z"
}
Errors
| Code | Description |
|---|
| 401 | Unauthorized |
| 404 | Key not found |
Delete key
Requires ownership of the key.
Response
Errors
| Code | Description |
|---|
| 401 | Unauthorized |
| 404 | Key not found |
Validate key
The
POST /api/keys/validate endpoint is planned for a future release. API key validation is currently available through the backend endpoint
POST /api/validate-key, which uses SHA-256 hash comparison.
Request body
| Field | Type | Required | Description |
|---|
apiKey | string | Yes | The full API key. Must start with the sk_ prefix. |
Response
{
"valid": true,
"userId": "user-a1b2c3d4",
"email": "user@example.com",
"plan": "solo",
"subscriptionStatus": "active",
"features": ["dashboard", "marketplace", "analytics"]
}
| Field | Type | Description |
|---|
valid | boolean | Whether the key is valid |
userId | string | User identifier |
email | string | User email address |
plan | string | Current subscription plan (solo, collective, label, or network) |
subscriptionStatus | string | Stripe subscription status (for example, active, past_due, canceled) |
features | string[] | List of features available to the user |
How it works
- The key prefix (first 10 characters) is used for a fast database lookup.
- Candidate keys matching the prefix are compared using
bcrypt.compare against the stored hash.
- On match, the user’s profile and subscription information are returned.
Errors
| Code | Description |
|---|
| 400 | Missing or non-string apiKey in the request body |
| 401 | Key does not start with sk_ or no matching key found |
| 500 | Validation failed due to a server error |
