Authentication

Learn how to authenticate with the Metaculus API using token-based authentication

Authentication Overview

The Metaculus API uses token-based authentication for all API requests. You must include a valid API token in the Authorization header of every request.

All API requests require valid authentication credentials. Unauthenticated requests will be rejected with a 401 Unauthorized error.

Getting Your API Token

To obtain your API token:

1. Log in to your Metaculus account
2. Navigate to your Account Settings
3. Scroll to the “API Access” section
4. Click to generate a new token or view your existing token

Keep your API token secret! Anyone with your token can make API requests on your behalf. Never commit tokens to version control or share them publicly.

Token Format

API tokens are 40-character hexadecimal strings, for example:

9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Making Authenticated Requests

Include your token in the Authorization header with the Token prefix:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

The format is: Token (literal string) + single space + your API token.

Example Requests

cURL

curl "https://www.metaculus.com/api/posts/" \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"

Authentication Errors

Common authentication error responses:

401 Unauthorized - Missing Token

{
  "detail": "Authentication credentials were not provided."
}

Solution: Ensure you’ve included the Authorization header in your request.

401 Unauthorized - Invalid Token

{
  "detail": "Invalid token."
}

Solution: Verify your token is correct. Generate a new token from your account settings if needed.

403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

Solution: You’re authenticated but don’t have permission to access this resource. Check if the resource requires special permissions or if you’re accessing a private tournament.

Token Security Best Practices

Follow these security practices to protect your API token:

Use Environment Variables

Never hardcode tokens in your source code. Use environment variables instead:

Python

import os

API_TOKEN = os.environ.get('METACULUS_API_TOKEN')

if not API_TOKEN:
    raise ValueError("METACULUS_API_TOKEN environment variable not set")

headers = {'Authorization': f'Token {API_TOKEN}'}

Rotate Tokens Regularly

For production applications, consider rotating your API tokens periodically:

1. Generate a new token from your account settings
2. Update your application to use the new token
3. Revoke the old token once migration is complete

You can also rotate your API token programmatically using the API:

cURL

curl -X POST "https://www.metaculus.com/api/auth/api-key/rotate/" \
  -H "Authorization: Token YOUR_CURRENT_TOKEN"

After rotating your token, your old token will be immediately invalidated. Make sure to update your application with the new token before the rotation completes.

Limit Token Exposure

• Don’t log tokens in application logs
• Don’t commit tokens to version control (.env files should be in .gitignore)
• Don’t share tokens in public channels or forums
• Use separate tokens for different applications or environments

Token Usage for Bots

API tokens are the recommended authentication method for automated bots and integrations. Session-based authentication is primarily for web users.

If you’re building a forecasting bot or automated system:

1. Generate a dedicated API token for your bot
2. Consider creating a separate Metaculus account for your bot
3. Clearly indicate in your bot’s profile that it’s automated
4. Respect rate limits to avoid disrupting the service

Testing Authentication

Test your authentication setup with this simple request:

curl -i "https://www.metaculus.com/api/posts/?limit=1" \
  -H "Authorization: Token YOUR_API_TOKEN"

Successful authentication returns a 200 status code:

HTTP/2 200
content-type: application/json
...

Failed authentication returns a 401 status code:

HTTP/2 401
content-type: application/json

{"detail":"Authentication credentials were not provided."}