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.

POST /auth/api-keys

​
Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token

​
Request Body

{
  "name": "Production Backend Key",
  "permission_level": "read_write"
}
ParameterTypeRequiredDescription
namestringYesDescriptive name for the API key
permission_levelstringYesPermission 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.

GET /auth/api-keys

​
Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token

​
Query Parameters

ParameterTypeRequiredDescription
statusstringNoFilter by status: active or revoked
limitintegerNoMaximum number of keys to return (default: 20, max: 100)
offsetintegerNoNumber 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}

​
Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token

​
Path Parameters

ParameterTypeRequiredDescription
keyIdstringYesID 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}

​
Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token

​
Path Parameters

ParameterTypeRequiredDescription
keyIdstringYesID of the API key to update

​
Request Body

{
  "name": "Updated Name",
  "expiration_days": 180  // Updates expiration to 180 days from now
}
ParameterTypeRequiredDescription
namestringNoNew name for the API key
expiration_daysintegerNoNew 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}

​
Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. Your API access token

​
Path Parameters

ParameterTypeRequiredDescription
keyIdstringYesID 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.

GET /auth/user

​
Headers

HeaderValueDescription
AuthorizationBearer TOKENRequired. 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 StatusError CodeDescription
400invalid_requestThe request was invalid
401unauthorizedAuthentication failed
403forbiddenInsufficient permissions
404not_foundResource not found
409resource_existsResource already exists
422validation_failedValidation failed
429rate_limitedToo many requests
500server_errorInternal 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.