This document provides detailed information about the authentication endpoints of the Plexe Platform API.
API Keys
Create API Key
Creates a new API key for your account.
| Header | Value | Description |
|---|
Authorization | Bearer TOKEN | Required. Your API access token |
Request Body
{
"name": "Production Backend Key",
"permission_level": "read_write"
}
| Parameter | Type | Required | Description |
|---|
name | string | Yes | Descriptive name for the API key |
permission_level | string | Yes | Permission level: read_only or read_write |
Response
{
"key_id": "key_abc123def456",
"name": "Production Backend Key",
"key": "plx_sk_987654321abcdefg...", // Full key shown ONLY once
"permission_level": "read_write",
"created_at": "2024-05-01T12:00:00Z",
"expires_at": "2024-07-30T12:00:00Z", // Or null if no expiration
"created_by": "user@example.com"
}
The full API key value (key field) is displayed only once when the key is created. Store it securely as you won’t be able to retrieve it again.
List API Keys
Returns a list of all API keys for your account.
| Header | Value | Description |
|---|
Authorization | Bearer TOKEN | Required. Your API access token |
Query Parameters
| Parameter | Type | Required | Description |
|---|
status | string | No | Filter by status: active or revoked |
limit | integer | No | Maximum number of keys to return (default: 20, max: 100) |
offset | integer | No | Number of keys to skip for pagination (default: 0) |
Response
{
"keys": [
{
"key_id": "key_abc123def456",
"name": "Production Backend Key",
"key_prefix": "plx_sk_9876", // First 4 digits + last 4 digits for identification
"key_suffix": "defg",
"permission_level": "read_write",
"created_at": "2024-05-01T12:00:00Z",
"expires_at": "2024-07-30T12:00:00Z",
"last_used_at": "2024-05-10T15:22:43Z",
"status": "active",
"created_by": "user@example.com"
},
{
"key_id": "key_ghi789jkl012",
"name": "Development Key",
"key_prefix": "plx_sk_1234",
"key_suffix": "zyxw",
"permission_level": "admin",
"created_at": "2024-04-15T09:30:00Z",
"expires_at": null,
"last_used_at": "2024-05-11T08:17:22Z",
"status": "active",
"created_by": "admin@example.com"
}
],
"pagination": {
"total": 5,
"limit": 20,
"offset": 0,
"has_more": false
}
}
Get API Key
Retrieves details for a specific API key.
GET /auth/api-keys/{keyId}
| Header | Value | Description |
|---|
Authorization | Bearer TOKEN | Required. Your API access token |
Path Parameters
| Parameter | Type | Required | Description |
|---|
keyId | string | Yes | ID of the API key to retrieve |
Response
{
"key_id": "key_abc123def456",
"name": "Production Backend Key",
"key_prefix": "plx_sk_9876",
"key_suffix": "defg",
"permission_level": "read_write",
"created_at": "2024-05-01T12:00:00Z",
"expires_at": "2024-07-30T12:00:00Z",
"last_used_at": "2024-05-10T15:22:43Z",
"status": "active",
"created_by": "user@example.com",
"usage_stats": {
"requests_last_24h": 156,
"requests_last_7d": 1287,
"requests_last_30d": 4583
}
}
Update API Key
Updates the name or expiration of an API key.
PATCH /auth/api-keys/{keyId}
| Header | Value | Description |
|---|
Authorization | Bearer TOKEN | Required. Your API access token |
Path Parameters
| Parameter | Type | Required | Description |
|---|
keyId | string | Yes | ID of the API key to update |
Request Body
{
"name": "Updated Name",
"expiration_days": 180 // Updates expiration to 180 days from now
}
| Parameter | Type | Required | Description |
|---|
name | string | No | New name for the API key |
expiration_days | integer | No | New expiration period (in days) from current date |
Response
{
"key_id": "key_abc123def456",
"name": "Updated Name",
"key_prefix": "plx_sk_9876",
"key_suffix": "defg",
"permission_level": "read_write",
"created_at": "2024-05-01T12:00:00Z",
"expires_at": "2024-10-28T12:00:00Z", // Updated expiration
"last_used_at": "2024-05-10T15:22:43Z",
"status": "active",
"created_by": "user@example.com"
}
You cannot change the permission level of an existing key. Create a new key with the desired permissions instead.
Revoke API Key
Revokes (invalidates) an API key, preventing its further use.
DELETE /auth/api-keys/{keyId}
| Header | Value | Description |
|---|
Authorization | Bearer TOKEN | Required. Your API access token |
Path Parameters
| Parameter | Type | Required | Description |
|---|
keyId | string | Yes | ID of the API key to revoke |
Response
{
"key_id": "key_abc123def456",
"status": "revoked",
"revoked_at": "2024-05-11T14:30:45Z"
}
Revoking an API key is permanent and cannot be undone. Applications using the revoked key will immediately lose access.
User Management
The following endpoint is available to retrieve user information for the currently authenticated user.
Get Current User
Returns information about the currently authenticated user.
| Header | Value | Description |
|---|
Authorization | Bearer TOKEN | Required. Your API access token |
Response
{
"user_id": "user_abc123",
"email": "user@example.com",
"name": "Example User",
"user_name": "user",
"credits": 1000,
"consumption": 50,
"is_active": true,
"has_api_key": true
}
Multi-Factor Authentication will be available in a future release.
Error Codes
| HTTP Status | Error Code | Description |
|---|
| 400 | invalid_request | The request was invalid |
| 401 | unauthorized | Authentication failed |
| 403 | forbidden | Insufficient permissions |
| 404 | not_found | Resource not found |
| 409 | resource_exists | Resource already exists |
| 422 | validation_failed | Validation failed |
| 429 | rate_limited | Too many requests |
| 500 | server_error | Internal server error |
Rate Limits
Authentication endpoints have rate limits to prevent abuse:
- Key creation: 10 requests per hour
- Authentication attempts: 10 failed attempts per 15 minutes
Exceeding these limits will result in a 429 Too Many Requests response. 
