Authentication

How the username and token credentials work, where they come from, and the error responses you get when they are missing or wrong.

Authentication#

The ID Generator authenticates every request with a username and a token carried in the request body. There are no headers, bearer tokens, or query-parameter credentials; Hep.gg reads both fields from the body only.

Where credentials come from#

Keys are minted in the hep.gg dashboard under ID Generator -> API Keys. There is no public "create a key" endpoint.

• You choose the username. hep.gg generates the token.
• The username is lowercased server-side and is global across Hep.gg, not scoped to your account. Pick something unique; if the name is taken, the dashboard tells you before you create the key.
• A single hep.gg account can hold as many keys as you need. Each key tracks its own generation count.

How the check works#

On each request Hep.gg lowercases the supplied username, looks up the matching key, and compares the stored secret against your token with an exact string match. If either field is missing, or the lookup or comparison fails, the request is rejected before any ID is generated.

Suspension and rotation#

When a key is suspended or rotated from the dashboard, Hep.gg simply has a different secret on file, so your old token stops matching and requests return 401 Invalid username or token. Rotate the token in the dashboard and update your integration to recover.

Error responses#

Both errors are returned as JSON in the shape { "error": "..." }. Authentication is checked before the type field, so a bad credential always returns 401 regardless of what you were trying to generate.

Example#

curl -X POST https://id.hep.gg/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-bot",
    "token": "<your-token>",
    "type": "uuid"
  }'

const res = await fetch("https://id.hep.gg/", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "my-bot",
    token: "<your-token>",
    type: "uuid",
  }),
});
 
if (res.status === 401) {
  throw new Error("ID Generator rejected the credentials");
}
const { id } = await res.json();