Authentication

Quick Access: Manage API Keys

LangMart uses API keys for authenticating requests. This guide covers how to create, use, and manage your API keys.

Authentication Methods

---

API Key Authentication

All API requests require a valid API key in the Authorization header.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl https://api.langmart.ai/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"

Python Example

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key-here",
    base_url="https://api.langmart.ai/v1"
)

JavaScript Example

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'sk-your-api-key-here',
    baseURL: 'https://api.langmart.ai/v1'
});

---

API Key Management

Create API Key

POST /api/keys

Request Body:

{
  "name": "My Production Key",
  "permissions": ["read", "write"],
  "expires_at": "2025-12-31T23:59:59Z"
}

Response:

{
  "id": "key_abc123",
  "name": "My Production Key",
  "key": "sk-abc123def456...",
  "permissions": ["read", "write"],
  "created_at": "2025-01-10T00:00:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

Important: The full API key is only shown once. Store it securely.

List API Keys

GET /api/keys

Response:

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "My Production Key",
      "key_prefix": "sk-abc1...f456",
      "permissions": ["read", "write"],
      "created_at": "2025-01-10T00:00:00Z",
      "last_used_at": "2025-01-10T12:00:00Z"
    }
  ]
}

Delete API Key

DELETE /api/keys/{key_id}

Response:

{
  "success": true,
  "message": "API key deleted"
}

Rotate API Key

Generate a new key while invalidating the old one:

POST /api/keys/{key_id}/rotate

Response:

{
  "id": "key_abc123",
  "key": "sk-new-key-value...",
  "rotated_at": "2025-01-10T00:00:00Z"
}

---

API Key Permissions

Permission Examples

Read-only key (for monitoring):

{"permissions": ["read"]}

Standard key (for applications):

{"permissions": ["read", "write"]}

Admin key (for management):

{"permissions": ["read", "write", "admin"]}

---

API Key Types

Permanent Keys

• Created manually via dashboard or API
• Don't expire unless you set an expiration date
• Best for: production applications

Temporary Keys

POST /api/keys/temporary

Request Body:

{
  "name": "Demo Key",
  "duration_hours": 24,
  "permissions": ["read", "write"]
}

Response:

{
  "id": "key_temp_abc123",
  "key": "sk-temp-abc123...",
  "expires_at": "2025-01-11T00:00:00Z"
}

Best for: demos, testing, short-term access

---

Validate API Key

Check if an API key is valid:

GET /v1/auth/validate

Headers:

Authorization: Bearer YOUR_API_KEY

Response (valid key):

{
  "valid": true,
  "user_id": "user_abc123",
  "permissions": ["read", "write"],
  "expires_at": null
}

Response (invalid key):

{
  "valid": false,
  "error": "Invalid or expired API key"
}

---

Guest Access

Try LangMart without creating an account:

POST /v1/auth/guest

Response:

{
  "api_key": "sk-guest-abc123...",
  "expires_at": "2025-01-10T01:00:00Z",
  "limits": {
    "requests_per_hour": 10,
    "models": ["groq/llama-3.3-70b-versatile"]
  }
}

Limitations:

• 1-hour expiration
• Limited to 10 requests
• Access to select free models only
• No persistence (conversation history lost)

---

OAuth Authentication

For web-based login, LangMart supports OAuth providers:

Available Providers

GET /v1/auth/providers

Response:

{
  "providers": [
    {"id": "google", "name": "Google", "enabled": true},
    {"id": "github", "name": "GitHub", "enabled": true}
  ]
}

OAuth Flow

1. Redirect to authorization URL:

   GET /v1/auth/authorize?provider=google&redirect_uri=YOUR_CALLBACK_URL

2. User authenticates with provider

3. Callback with authorization code:

   GET /v1/auth/callback?code=AUTH_CODE&state=STATE

4. Receive tokens:

   {
     "access_token": "...",
     "refresh_token": "...",
     "expires_in": 3600
   }

---

Security Best Practices

1. Never Expose Keys in Client Code

// BAD - Key visible in browser
const client = new OpenAI({
    apiKey: 'sk-abc123...',  // NEVER DO THIS
});

// GOOD - Use server-side proxy
const response = await fetch('/api/chat', {
    method: 'POST',
    body: JSON.stringify({ message: 'Hello' })
});

2. Use Environment Variables

# .env file (never commit to git)
LANGMART_API_KEY=sk-your-key-here

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("LANGMART_API_KEY"),
    base_url="https://api.langmart.ai/v1"
)

3. Rotate Keys Regularly

# Schedule key rotation
def rotate_production_key():
    response = requests.post(
        "https://api.langmart.ai/api/keys/key_abc123/rotate",
        headers={"Authorization": f"Bearer {admin_key}"}
    )
    new_key = response.json()["key"]
    update_secret_manager(new_key)

4. Use Minimal Permissions

{
  "name": "Read-Only Analytics",
  "permissions": ["read"]
}

5. Set Expiration Dates

{
  "name": "Contractor Access",
  "permissions": ["read", "write"],
  "expires_at": "2025-03-31T23:59:59Z"
}

6. Monitor Key Usage

Check usage in the dashboard or via API:

curl https://api.langmart.ai/api/account/request-logs?api_key_id=key_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Error Responses

Invalid API Key (401)

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided"
  }
}

Expired API Key (401)

{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "API key has expired"
  }
}

Insufficient Permissions (403)

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "API key lacks required permissions: admin"
  }
}

---

Platform Links

Related Documentation

• OpenAI-Compatible API - Using your API key
• Request Logs - Monitor key usage
• Errors - Authentication error codes