Authentication & API Tokens

What it is

To interact with the VerseDB API, you need to authenticate with a Bearer token. Tokens act as your secure access key and allow API requests on your behalf without exposing your password.

Important: All API endpoints require authentication. There is no anonymous public access.

Where to get your token

To create and manage API tokens:

1. Log into your VerseDB account
2. Navigate to Settings then API Tokens
3. Or go directly to: versedb.com/user/api-tokens
4. Click Create New Token
5. Give your token a descriptive name (e.g., "Mobile App", "Discord Bot")
6. Select the scopes you need
7. Click Create to generate your token
8. Copy the token immediately - it will only be shown once

Important: Store your token securely. You won't be able to see it again after creation. If you lose it, you'll need to generate a new one.

Using the token in API requests

Include your token in the Authorization header of every request:

Authorization: Bearer your-api-token-here

Example: cURL

curl -H "Authorization: Bearer your-token-here" \
     https://versedb.com/api/user

Example: JavaScript (fetch)

fetch('https://versedb.com/api/user', {
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
  }
})

Example: Python (requests)

import requests

headers = {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
}

response = requests.get('https://versedb.com/api/user', headers=headers)

Token Scopes

When creating a token, select only the scopes your application needs. This follows the principle of least privilege for better security.

Available Scopes

• read:public - Read public comic data (series, issues, characters, creators, etc.)
• read:self - Read your own profile and account data
• lists:collection - Manage your collections
• lists:user_lists - Manage user lists and wishlist
• lists:pulllist - Manage your pull list
• lists:read - Track reading progress
• lists:follow - Follow/unfollow titles, characters, podcasts

Best practice: Only grant the scopes your application actually needs.

Managing multiple tokens

You can create multiple tokens for different purposes:

• Personal scripts - One token for your automation scripts
• Mobile app - Separate token for your phone
• Third-party integrations - Different tokens for each service
• Development/testing - Test tokens that can be safely revoked

Benefits:

• Revoke compromised tokens without affecting others
• Track usage per application
• Grant different scopes to different tools

Token security best practices

Do:

• Store tokens in environment variables, not hardcoded
• Use secrets management tools (e.g., .env files, Azure Key Vault)
• Revoke unused tokens regularly
• Use HTTPS only for all API requests
• Implement token rotation for long-running apps
• Give tokens descriptive names to track usage

Don't:

• Never commit tokens to Git repositories
• Don't share tokens publicly (Discord, forums, etc.)
• Avoid storing tokens in client-side JavaScript
• Don't use the same token across multiple untrusted apps
• Never log tokens in application logs

Revoking and regenerating tokens

To revoke a token:

1. Go to Settings then API Tokens
2. Find the token you want to revoke
3. Click Delete or Revoke
4. The token will be immediately invalidated

When to revoke:

• Token may have been exposed or compromised
• No longer using the application/service
• Switching to a new token with different scopes
• Regular security rotation (e.g., every 90 days)

Troubleshooting authentication errors

401 Unauthorized

Problem: Token is missing, invalid, or expired Solutions:

• Check the Authorization header is properly formatted
• Verify token hasn't been revoked
• Regenerate token if necessary
• Ensure using Bearer prefix before token

403 Forbidden

Problem: Token lacks required scopes for the endpoint Solutions:

• Check token has appropriate scopes
• Create new token with correct scopes
• Verify endpoint requires the scope you think it does

402 Payment Required

Problem: Endpoint requires PRO subscription Solutions:

• Upgrade to PRO at versedb.com/subscription
• Use a different endpoint that doesn't require PRO

429 Too Many Requests

Problem: Rate limit exceeded Solutions:

• Implement exponential backoff in your client
• Upgrade to PRO for higher rate limits
• Reduce request frequency

Testing your token

Quick test to verify your token works:

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://versedb.com/api/user

If successful, you'll receive your profile data. If you get a 401, the token is invalid.