6. Authentication & Access Control

Authentication in Addonium is transport-level and author-defined. There is no mandated identity provider, OAuth flow, or Addonium account system. The spec only standardizes how the token gets from the host to the addon and how the addon states it needs one - never who is allowed to have one.

6.1 Open Addon (`type: "open"`)

auth is null. Every request the host makes is unauthenticated. This is the BeatBoss/Eclipse default today, and remains the zero-friction path for public content sources.

6.2 Locked Addon (`type: "locked"`)

auth describes how a client attaches proof of authorization. Exactly one method is chosen per addon:

{
  "auth": {
    "method": "bearer",
    "header": "Authorization",
    "scheme": "Bearer",
    "tokenGrant": "manual",
    "grantUrl": "https://example.com/get-token",
    "required": true
  }
}

`method`	How it works
`"bearer"`	Host sends `Authorization: Bearer <token>` on every request. Token is obtained out-of-band (`grantUrl`, license purchase, invite, etc.) and pasted into the host once.
`"url-token"`	The token is embedded directly in the base URL path (§7), e.g. `https://api.example.com/{token}/search`. No special header handling needed by the host - the whole URL is the credential. This is the simplest option and matches BeatBoss's and Eclipse's existing convention.
`"api-key"`	Host sends the token as a query parameter or custom header named in `paramName`/`header`.
`"signed"`	Every request must be signed (e.g. HMAC over method+path+timestamp) using a secret the addon issued. For authors who want replay protection without running a session store.
`"module-key"`	Only applicable to compiled modules (§9) - the module itself won't execute/decrypt without the correct key. Not used for plain HTTP addons.

tokenGrant documents (for humans, not enforced by the spec) how a user gets a token in the first place: "manual" (author hands it out), "self-serve" (a grantUrl the host can open), or "none" (pre-baked into distributed URLs, e.g. a paid Gumroad download that already contains a personal tokenized link).

requirements lists the author's own out-of-band conditions for granting access - anything they choose, e.g. joining a Discord server, holding a supporter role, or showing a purchase receipt. Each entry is a plain string or a { label, url?, detail? } object. It is display-only: hosts surface it at install time (§13) and never enforce it. What "authorized" means stays entirely between the author and the user:

{
  "auth": {
    "method": "url-token",
    "tokenGrant": "manual",
    "requirements": [
      {
        "label": "Join the Example Discord to request a token",
        "url": "https://discord.gg/example",
        "detail": "Ask in #addon-access; the author issues personal tokenized links."
      }
    ]
  }
}

6.3 What the spec does not do

Addonium never specifies a canonical login screen, payment processor, or account database. This is intentional - it's the part of "freedom" that matters most: an author can gate their addon with a $2 Ko-fi supporter role, a Discord invite check, a hardware dongle, or nothing weirder than a password, and none of that needs to be legible to the spec.