API Keys API
Generate and manage programmatic access keys
1 min readCreate and manage API keys for programmatic access. Generate new keys with custom names and optional expiration dates, list all active keys, update key metadata, and revoke keys when no longer needed. Each key can be scoped to specific permissions for security.
Available Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/auth/api-key/create | Create a new API key |
GET | /api/auth/api-key/list | List all API keys |
GET | /api/auth/api-key/get | Get API key details |
POST | /api/auth/api-key/update | Update an API key |
POST | /api/auth/api-key/delete | Delete an API key |
Endpoints
POST
/api/auth/api-key/createCreate a new API key
Create a new API key for programmatic API access. The full key is only returned once - store it securely.
Bearer Token•Scopes:
api-keys:writeRequest
curl -X POST "http://localhost:3030/api/auth/api-key/create" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"name":"My API Key","expiresIn":2592000,"scopes":["user:read","projects:read"],"metadata":{}}'const response = await fetch("http://localhost:3030/api/auth/api-key/create", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "My API Key",
"expiresIn": 2592000,
"scopes": [
"user:read",
"projects:read"
],
"metadata": {}
}),
});
const data = await response.json();
console.log(data);Body Parameters
| Name | Type | Description |
|---|---|---|
namerequired | string | Human-readable name for the keyMy API Key |
expiresIn | number | Expiration time in seconds (optional)2592000 |
scopes | string[] | Array of permission scopes to assign to this keyuser:read,projects:read |
metadata | object | Optional metadata object |
Response 200
API key created successfully
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
"key": "ba_1234567890abcdef...",
"id": "ak_abc123",
"name": "My API Key"
}
}Error Responses
401— Unauthorized - Invalid or missing authentication
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}403— Forbidden - Insufficient permissions
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}GET
/api/auth/api-key/listList all API keys
Get all API keys for the authenticated user. Note: The full key value is not returned.
Bearer Token•Scopes:
api-keys:readRequest
curl -X GET "http://localhost:3030/api/auth/api-key/list" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"const response = await fetch("http://localhost:3030/api/auth/api-key/list", {
method: "GET",
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json",
},
});
const data = await response.json();
console.log(data);Response 200
API keys retrieved successfully
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": [
{
"id": "ak_abc123",
"name": "My API Key",
"start": "ba_...xyz",
"createdAt": "2024-01-01T00:00:00.000Z",
"expiresAt": "2024-12-31T23:59:59.000Z",
"lastUsedAt": "2024-01-15T10:30:00.000Z",
"enabled": true,
"scopes": [
"user:read",
"projects:read"
],
"metadata": {}
}
]
}Error Responses
401— Unauthorized - Invalid or missing authentication
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}403— Forbidden - Insufficient permissions
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}GET
/api/auth/api-key/getGet API key details
Get details of a specific API key by ID.
Bearer Token•Scopes:
api-keys:readRequest
curl -X GET "http://localhost:3030/api/auth/api-key/get" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json"const response = await fetch("http://localhost:3030/api/auth/api-key/get", {
method: "GET",
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json",
},
});
const data = await response.json();
console.log(data);Query Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | API Key IDak_abc123 |
Response 200
API key retrieved successfully
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
"id": "ak_abc123",
"name": "My API Key",
"start": "ba_...xyz",
"createdAt": "2024-01-01T00:00:00.000Z",
"expiresAt": "2024-12-31T23:59:59.000Z",
"lastUsedAt": "2024-01-15T10:30:00.000Z",
"enabled": true,
"scopes": [
"user:read",
"projects:read"
],
"metadata": {}
}
}Error Responses
401— Unauthorized - Invalid or missing authentication
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}403— Forbidden - Insufficient permissions
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}POST
/api/auth/api-key/updateUpdate an API key
Update an existing API key's name, enabled status, or scopes.
Bearer Token•Scopes:
api-keys:writeRequest
curl -X POST "http://localhost:3030/api/auth/api-key/update" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"id":"ak_abc123","name":"Updated Key Name","enabled":true,"scopes":["string"],"metadata":{}}'const response = await fetch("http://localhost:3030/api/auth/api-key/update", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
"id": "ak_abc123",
"name": "Updated Key Name",
"enabled": true,
"scopes": [
"string"
],
"metadata": {}
}),
});
const data = await response.json();
console.log(data);Body Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | API Key IDak_abc123 |
name | string | Updated Key Name |
enabled | boolean | Enable or disable the keytrue |
scopes | string[] | |
metadata | object |
Response 200
API key updated successfully
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
"id": "ak_abc123",
"name": "My API Key",
"start": "ba_...xyz",
"createdAt": "2024-01-01T00:00:00.000Z",
"expiresAt": "2024-12-31T23:59:59.000Z",
"lastUsedAt": "2024-01-15T10:30:00.000Z",
"enabled": true,
"scopes": [
"user:read",
"projects:read"
],
"metadata": {}
}
}Error Responses
401— Unauthorized - Invalid or missing authentication
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}403— Forbidden - Insufficient permissions
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}POST
/api/auth/api-key/deleteDelete an API key
Permanently delete an API key. This action cannot be undone.
Bearer Token•Scopes:
api-keys:deleteRequest
curl -X POST "http://localhost:3030/api/auth/api-key/delete" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"id":"ak_abc123"}'const response = await fetch("http://localhost:3030/api/auth/api-key/delete", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
"id": "ak_abc123"
}),
});
const data = await response.json();
console.log(data);Body Parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | API Key ID to deleteak_abc123 |
Response 200
API key deleted successfully
{
"success": true,
"status": 200,
"code": "OK",
"message": "Operation completed successfully",
"data": {
"success": true
}
}Error Responses
401— Unauthorized - Invalid or missing authentication
{
"success": false,
"status": 401,
"code": "UNAUTHORIZED",
"message": "Authentication required"
}403— Forbidden - Insufficient permissions
{
"success": false,
"status": 403,
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}