Authentication

The MTG Rack API supports two authentication methods: personal API keys for your own scripts and automations, and OAuth2 tokens for third-party applications that act on behalf of other users. This guide covers both methods, when to use each, and how to keep your credentials secure.

API Keys vs. OAuth2 — When to Use Which

Choose based on whose data your integration will access:

• API Keys — use when your tool accesses your own account. Examples: a personal Discord bot that looks up prices, a Google Sheets script that syncs your collection, a cron job that imports cards from another platform nightly. API keys are simpler to set up — no redirect flows, no token refresh.
• OAuth2 — use when you are building an app that other MTG Rack users will authorize. Examples: a deck-sharing website, a tournament organizer that reads participants' decklists, a community analytics tool. OAuth2 ensures users grant explicit consent and can revoke access at any time. See the OAuth2 Integration guide for the full authorization code flow.

Creating an API Key

Follow these steps to create a personal API key:

1. Open the Developer Portal and navigate to the API Keys tab.
2. Click Create Key.
3. Give the key a descriptive name that identifies its purpose (e.g., "Discord Price Bot", "Spreadsheet Sync", "Backup Script"). This helps you manage multiple keys later.
4. Select the scopes the key needs (see below). Follow the principle of least privilege — only grant the permissions your integration actually requires.
5. Click Generate. Your key is displayed once in full. Copy it immediately and store it in a secure location (password manager, environment variable, or encrypted secrets store).

Scopes

Scopes control what an API key or OAuth2 token can access. Each scope grants access to a specific set of operations. Request only what your integration needs:

• collection:read — view collection entries, quantities, conditions, and values.
• collection:write — add, update, and remove collection entries. Requires collection:read implicitly.
• decks:read — view decks, decklists, and deck metadata.
• decks:write — create, update, and delete decks. Requires decks:read implicitly.
• cards:read — search the card database, retrieve card details, printings, prices, and rulings. This scope accesses shared card data, not your personal collection.
• webhooks:manage — create, update, list, and delete webhook subscriptions.
• profile:read — read the authenticated user's profile information (username, email, plan tier).

Using Your API Key

Include your API key in every request using the Authorization header with the Bearer scheme:

curl https://mtgrack.com/api/v1/collection \
  -H "Authorization: Bearer mtr_k_your_api_key_here"

Or in JavaScript with fetch:

const response = await fetch("https://mtgrack.com/api/v1/collection", {
  headers: {
    "Authorization": "Bearer mtr_k_your_api_key_here",
    "Content-Type": "application/json",
  },
});

const { data, meta } = await response.json();
console.log(`You have ${meta.total} cards in your collection`);

Error Responses

Authentication-related errors return specific HTTP status codes:

• 401 Unauthorized — no token provided, token is malformed, or the token has been revoked. Check that your Authorization header is present and correctly formatted.
• 403 Forbidden — the token is valid but does not have the required scope for this endpoint. The error body includes the missing scope so you know what to add.
• 429 Too Many Requests — rate limit exceeded. See the Rate Limits page for details on quotas and retry strategies.

Token Security Best Practices

• Never commit keys to source control. Use environment variables or a secrets manager. Add .env to your .gitignore.
• Rotate keys periodically. Create a new key, update your integration, then revoke the old one.
• Revoke compromised keys immediately. If you suspect a key has been exposed — even if you are not sure — revoke it in the Developer Portal and create a replacement. Revocation is instant.
• Use separate keys per integration. If you have a Discord bot and a spreadsheet sync, give each its own key. That way you can revoke one without disrupting the other.
• Monitor usage. The Developer Portal shows API usage analytics per key. If you see unexpected spikes, investigate immediately.