Authentication & API Tokens

What it is

To interact with your personal data using the VerseDB API — like Collections, Wishlists, Pull Lists, or reading progress — you'll need to authenticate with a Bearer token.

Tokens act as your secure access key and allow API requests to be made on your behalf without exposing your password.

Where to get your token

To create and manage API tokens:

1. Log into your VerseDB account
2. Navigate to Settings → API section
3. Or go directly to: https://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 permissions/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 authenticated request:

Authorization: Bearer your-api-token-here

Example: cURL

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
     https://versedb.com/api/v1/user/collection

Example: JavaScript (fetch)

fetch('https://versedb.com/api/v1/user/collection', {
  headers: {
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGc...',
    'Content-Type': 'application/json'
  }
})

Example: Python (requests)

import requests

headers = {
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGc...',
    'Content-Type': 'application/json'
}

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

Token Permissions (Scopes)

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

Read Permissions

• read:public – Browse public content (series, issues, characters, creators)
• read:self – Read your own account data and profile
• read:collection – View your collection
• read:wishlist – View your wishlist
• read:pulllist – View your pull list
• read:read – View your reading history

Write Permissions

• write:collection – Add, edit, and remove items from your collection
• write:wishlist – Add, edit, and remove items from your wishlist
• write:pulllist – Add and remove series from your pull list
• write:read – Mark issues as read/unread
• write:follow – Follow/unfollow titles and series

Combined Permissions

• lists:collection – Full read/write access to collection
• lists:wishlist – Full read/write access to wishlist
• lists:pulllist – Full read/write access to pull list
• lists:read – Full read/write access to reading tracker
• lists:follow – Full read/write access to follows

Best practice: Use combined permissions for simpler token management, or separate read/write for fine-grained control.

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 permissions 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 → API section
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 permissions
• Regular security rotation (e.g., every 90 days)

Public vs authenticated endpoints

Public endpoints (no token required):

• GET /api/series - Browse series
• GET /api/issues - Browse issues
• GET /api/characters - Browse characters
• GET /api/creators - Browse creators
• GET /api/users/{id}/profile - View public profiles

Authenticated endpoints (token required):

• GET /api/user/collection - Your collection
• POST /api/user/collection - Add to collection
• GET /api/user/wishlist - Your wishlist
• POST /api/user/pulllist - Manage pull list
• GET /api/user/profile - Your private profile data

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 permissions for the endpoint
Solutions:

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

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/v1/user/profile

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

Next step: Learn about rate limits in "Understanding API Rate Limits on VerseDB"