Authentication

TPMJS uses API keys for authentication. Some endpoints are public and don't require authentication, while others require a valid API key to access.

Public Endpoints (No Auth Required)

• GET /api/tools - List and search tools
• GET /api/tools/:id - Get tool details
• GET /api/tools/trending - Get trending tools
• GET /api/collections - List public collections
• GET /api/collections/:uid - Get collection details

Protected Endpoints (Auth Required)

• POST /api/tools/:id/rate - Rate a tool
• POST /api/tools/:id/reviews - Write a review
• POST /api/collections - Create a collection
• POST /api/agents - Create an agent
• GET /api/agents - List your agents

To get an API key, you need to create a TPMJS account and generate a key from your dashboard.

1. Sign up or log in at tpmjs.com
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy your key and store it securely

Include your API key in the Authorization header using the Bearer scheme.

Header Format

Authorization: Bearer YOUR_API_KEY

cURL Example

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://tpmjs.com/api/agents"

JavaScript/TypeScript Example

const API_KEY = process.env.TPMJS_API_KEY;

const response = await fetch('https://tpmjs.com/api/agents', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Python Example

import os
import requests

API_KEY = os.environ.get('TPMJS_API_KEY')

response = requests.get(
    'https://tpmjs.com/api/agents',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

data = response.json()

401 Unauthorized

Returned when no API key is provided or the key is invalid.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Please provide a valid API key."
  }
}

403 Forbidden

Returned when the API key is valid but lacks permission for the requested action.

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource."
  }
}

429 Rate Limited

Returned when you've exceeded the rate limit for your API key.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again in 60 seconds."
  }
}

TPMJS enforces rate limits to ensure fair usage and protect the API from abuse.

Rate Limit Headers

Every response includes rate limit information in headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1704067200

• Never commit API keys to version control. Use environment variables instead.
• Rotate keys regularly. Generate new keys periodically and revoke old ones.
• Use separate keys for development and production. This limits the impact if a key is compromised.
• Monitor usage. Check your API usage in the dashboard to detect unusual activity.
• Revoke compromised keys immediately. If you suspect a key has been exposed, revoke it and generate a new one.

Environment Variables Example

# .env.local (add to .gitignore)
TPMJS_API_KEY=your_api_key_here

# In your code
const apiKey = process.env.TPMJS_API_KEY;