API Key Management

PrerequisitesCopied!

• AlphaLens account (with correct tiering).

• User ID for API key creation

• Admin or owner permissions for company-wide key management

Creating an API KeyCopied!

Endpoint: POST /api/v1/users/{user_id}/api-keys

Create a new API key for a user. The raw key value is only shown once in the response - make sure to store it securely.

Required Parameters:

• name (string): A name to identify your API key

• expires_at (date-time, optional): When the key should expire

Example request payload:

{
    "name": "My API Key"
}

Access Control:

• Only accessible by the user themselves or Admins of their company

Returns:

An object containing:

• id: Unique identifier for the key

• name: The name you provided

• key: The actual API key value (only shown once)

• created_at: Creation timestamp

• expires_at: Expiration date (if set)

• is_active: Whether the key is currently active

Listing API KeysCopied!

Endpoint: GET /api/v1/users/{user_id}/api-keys

Retrieve all API keys for a user. Note that this only returns hashed keys, not the original values.

Access Control:

• Only accessible by the user themselves or Admins of their company

Returns:

A list of APIKeyResponse objects containing:

• id: Key identifier

• name: Key name

• created_at: Creation timestamp

• expires_at: Expiration date (if set)

• last_used_at: When the key was last used

• is_active: Current status

Revoking an API KeyCopied!

Endpoint: POST /api/v1/users/{user_id}/api-keys/{key_id}/revoke

Revoke an existing API key to prevent further use.

Access Control:

• Only accessible by the key owner or Admins of their company

Status Codes:

• 204: Successfully revoked

• 401: Invalid token/authentication

• 403: Insufficient permissions

• 404: Key not found

Using API KeysCopied!

To use an API key for authentication, include it in the request header:

API-Key: your_api_key_here

Best PracticesCopied!

1. Store API keys securely and never expose them in client-side code

2. Use descriptive names to easily identify different keys

3. Regularly rotate keys for security

4. Set expiration dates for temporary access

5. Revoke unused or compromised keys immediately

6. Keep track of which keys are used for what purpose

Security NotesCopied!

• API keys are sensitive credentials - treat them like passwords

• The full key value is only shown once when created

• Keys can't be recovered if lost - create a new one instead

• All key usage is logged for security monitoring

• Keys automatically expire if an expiration date is set