Skip to content
VerseDB

VerseDB API Guide

8 articles

All Collections

Authentication & API Tokens

All VerseDB API endpoints require a Bearer token — there is no anonymous access. Tokens act as your access key so you don't have to send your password with every request.

Create a Token#

  1. Go to versedb.com/my/apps
  2. Click Create New Token
  3. Give it a descriptive name — "Mobile App", "Discord Bot", etc.
  4. Select only the scopes you need (principle of least privilege)
  5. Click Create and copy the token immediately — it's shown only once

Warning

If you lose a token, you can't retrieve it — generate a new one and revoke the old.

Use It in Requests#

Include the token in the Authorization header of every request.

# cURL
curl -H "Authorization: Bearer YOUR_TOKEN" https://versedb.com/api/user

// JavaScript (fetch)
fetch('https://versedb.com/api/user', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
})

# Python (requests)
import requests
requests.get('https://versedb.com/api/user',
             headers={'Authorization': 'Bearer YOUR_TOKEN'})

A successful call to /api/user returns your profile. A 401 means the token is missing, invalid, or revoked.

The official TypeScript and Python SDKs take the token once, when you create the client, and send it on every call for you.

Scopes#

Scope What it grants
read:public Public comic data (series, issues, characters, creators)
read:user Your own profile and account data
write:collection Manage your collection
write:list Create and manage your lists
write:wishlist Add and remove wishlist issues
lookup:barcode Look up an issue by barcode
write:pull-list Manage your pull list
write:read-status Mark issues read or unread
write:follows Follow titles, characters, podcasts

Create separate tokens for different applications — a compromised mobile token shouldn't expose your Discord bot.

Security#

  • Store tokens in environment variables or a secrets manager
  • Use HTTPS for every request
  • Rotate tokens periodically (e.g., every 90 days)
  • Give each integration its own token so you can revoke individually
  • Commit tokens to Git or paste them in Discord/forums
  • Put tokens in client-side JavaScript that ships to users
  • Reuse one token across multiple untrusted apps
  • Log tokens in application logs

Revoke a token any time from My Apps. Revocation is immediate.

Common Errors#

Code Meaning Fix
401 Unauthorized Token missing, invalid, or revoked Check the header format and regenerate if needed
403 Forbidden Token lacks required scope Create a new token with the right scopes
402 Payment Required Endpoint needs PRO Upgrade at /subscription or use a non-PRO endpoint
429 Too Many Requests Rate limit hit Back off exponentially; PRO has higher limits