Authentication API

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

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.

GET /auth/api-keys

Headers

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}

Headers

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}

Headers

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}

Headers

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.

GET /auth/user

Headers

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.

Introduction

Plexe Python Library

Plexe Platform

API Keys

Create API Key

Headers

Request Body

Response

List API Keys

Headers

Query Parameters

Response

Get API Key

Headers

Path Parameters

Response

Update API Key

Headers

Path Parameters

Request Body

Response

Revoke API Key

Headers

Path Parameters

Response

User Management

Get Current User

Headers

Response

Error Codes

Rate Limits

​API Keys

​Create API Key

​Headers

​Request Body

​Response

​List API Keys

​Headers

​Query Parameters

​Response

​Get API Key

​Headers

​Path Parameters

​Response

​Update API Key

​Headers

​Path Parameters

​Request Body

​Response

​Revoke API Key

​Headers

​Path Parameters

​Response

​User Management

​Get Current User

​Headers

​Response

​Error Codes

​Rate Limits

API Keys

Create API Key

Headers

Request Body

Response

List API Keys

Headers

Query Parameters

Response

Get API Key

Headers

Path Parameters

Response

Update API Key

Headers

Path Parameters

Request Body

Response

Revoke API Key

Headers

Path Parameters

Response

User Management

Get Current User

Headers

Response

Error Codes

Rate Limits