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#
- Go to versedb.com/my/apps
- Click Create New Token
- Give it a descriptive name — "Mobile App", "Discord Bot", etc.
- Select only the scopes you need (principle of least privilege)
- 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.
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 |