ID Generator

One endpoint on id.hep.gg that mints IDs in eight flavours, authenticated with a username and token from the hep.gg dashboard.

ID Generator#

The ID Generator is a single HTTP endpoint that mints one identifier per call in eight flavours: uuid, nanoid, 2fa, license, words, snowflake, keypair, and cuid. You pick the flavour with the type field in the request body, pass any per-type options alongside it, and Hep.gg returns the generated value as JSON.

Authentication#

Every request carries a username and a token in the request body. Both are issued from the hep.gg dashboard, there is no public endpoint that creates a key.

• Mint a key in the dashboard under ID Generator -> API Keys. You choose the username; hep.gg generates the token.
• The username is global across Hep.gg and is lowercased server-side, so pick something unique. It is not namespaced per account.
• One hep.gg account can own as many keys as you need. Each key counts its own generations.
• The token is a secret. It is matched exactly against the key on file. Never print it client-side or commit it to source control.

If you suspend or rotate a key in the dashboard, Hep.gg stops recognising the old token and returns 401 Invalid username or token. See Authentication for the full model and error responses.

Quickstart#

The smallest working call: mint a 12-character URL-safe nanoid. Replace my-bot and the token with your own key.

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

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: "nanoid",
    length: 12,
  }),
});
const { id } = await res.json();
console.log(id); // e.g. "V1StGXR8_Z5j"

A successful call returns 200 with { "id": "<generated id>" }. The keypair type is the one exception, it returns a second privateID field. See Generate an ID for the request shape and ID types for every flavour and its options.

What is public#

The only public surface is POST https://id.hep.gg/. The dashboard CRUD routes for managing keys and reading stats live on the hep.gg API behind a session cookie and are not part of this developer API.