Authentication & API keys

Public reads work without credentials. Everything else needs a personal API key, sent as a bearer token.

API keys

• Format: gm_<prefix>_<secret>. The prefix (gm_a1b2c3d4) is shown in the list so you can tell keys apart.
• Create, rotate and revoke keys in Settings → API keys on the website. Keys can't manage keys: those endpoints refuse bearer tokens.
• The secret is shown once. Only its hash is stored, so a lost key can't be recovered: rotate it.
• Up to 10 active keys per account, optionally with an expiry (30, 90 or 365 days).
• A key acts as you, with your roles and permissions, narrowed by its scopes.

Authorization: Bearer gm_a1b2c3d4_Q2hhbmdlTWVJbkEuZW52RmlsZU5vdEluQ29kZTEy

curl

#!/usr/bin/env bash
set -euo pipefail
BASE_URL="${GLITCHMUG_API:-https://api.glitchmug.com/v1}"

curl -fsS "$BASE_URL/me" \
  -H "Authorization: Bearer $GLITCHMUG_TOKEN"

TypeScript

const baseUrl = process.env.GLITCHMUG_API ?? 'https://api.glitchmug.com/v1';

const res = await fetch(`${baseUrl}/me`, {
  headers: { Authorization: `Bearer ${process.env.GLITCHMUG_TOKEN}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const me = await res.json();
console.log(me.username, me.permissions);

Python

import json
import os
import urllib.request

base_url = os.environ.get("GLITCHMUG_API", "https://api.glitchmug.com/v1")
req = urllib.request.Request(
    f"{base_url}/me",
    headers={"Authorization": f"Bearer {os.environ['GLITCHMUG_TOKEN']}"},
)

with urllib.request.urlopen(req) as res:
    me = json.load(res)
    print(me["username"], me["permissions"])

Requests with a bearer token don't need cookies or CSRF tokens.

Scopes

GET requests need only mods:read, which every key has. Writes need the scope of the area:

Scope	Grants
mods:read	Read everything you can see on the site (always included)
mods:write	Create and edit your mods and versions, submit them
files:upload	Upload files and images
comments:write	Post, edit and delete comments
webhooks:manage	Manage your webhooks — needed even to list them

Other writes (likes, collections, reports, settings) are website-only for now.

Failures

Status	code	Meaning
401	invalid_api_key	Malformed, revoked or expired key
401	unauthenticated	No credentials on an endpoint that needs them
403	scope_missing	The key lacks the scope for this request
403	banned	The account is banned; its keys stop working
403	forbidden	You don't have the permission (a key never adds permissions)

See Errors for the response format.