Developer accounts

A StarPlan developer account is the smallest authentication primitive in the API. It owns one API key (rotatable), zero or more webhook subscriptions, and a usage log that powers GET /developers/usage.

`POST /v1/starplan/developers/register` (anonymous)

curl -X POST https://api.hfu.digital/v1/starplan/developers/register \
  -H 'Content-Type: application/json' \
  -d '{ "email": "you@example.com", "name": "My Integration" }'

Field	Type	Constraints
`email`	string	required, valid email, ≤ 254 chars
`name`	string	optional, ≤ 100 chars

Response (the only place the raw key ever appears):

{
  "data": {
    "id":         "dev…",
    "email":      "you@example.com",
    "name":       "My Integration",
    "apiKey":     "spk_AbCd1234EfGh5678…",
    "apiKeyHint": "5678",
    "createdAt":  "2026-04-26T12:00:00.000Z"
  },
  "message": "Save your API key securely — it will not be shown again."
}

409 Conflict — Email already registered is returned if the email is already in use. Re-registering an existing account is intentionally not supported — rotate the existing key instead, or deactivate and register fresh.

The server stores only a bcrypt hash and the last 4 characters of the key. There is no recovery path; if you lose the raw key, your only options are to rotate via the existing key (if you still have it) or deactivate the account and register a new one with a different email.

`GET /v1/starplan/developers/me`

curl https://api.hfu.digital/v1/starplan/developers/me \
  -H 'X-API-Key: spk_…'

{
  "data": {
    "id":          "dev…",
    "email":       "you@example.com",
    "name":        "My Integration",
    "apiKeyHint":  "5678",
    "isActive":    true,
    "createdAt":   "2026-04-26T12:00:00.000Z",
    "updatedAt":   "2026-04-26T12:00:00.000Z",
    "_count":      { "webhooks": 2 }
  }
}

The raw key is never returned here — only the 4-character hint.

`POST /v1/starplan/developers/regenerate-key`

curl -X POST https://api.hfu.digital/v1/starplan/developers/regenerate-key \
  -H 'X-API-Key: spk_…'

Issues a fresh spk_… key and immediately invalidates the old one. The response is the same shape as registration's data.apiKey / data.apiKeyHint pair, plus a message. Webhooks are not affected — they belong to the developer, not the key.

{
  "data": { "apiKey": "spk_NewKey…", "apiKeyHint": "wXyZ" },
  "message": "Save your new API key securely — it will not be shown again."
}

`POST /v1/starplan/developers/deactivate`

Soft-disables the developer account. Future requests with the key get 401 Unauthorized — Invalid or revoked API key. Webhooks remain in the database but their isActive state is unchanged — deactivating the account is the right escape hatch when you suspect the key has leaked, since matching at delivery time will still rely on the key being valid.

curl -X POST https://api.hfu.digital/v1/starplan/developers/deactivate \
  -H 'X-API-Key: spk_…'

Response: { "message": "Developer key deactivated." }. There is currently no anonymous re-activation path — contact the platform team if you need to recover the account.

`GET /v1/starplan/developers/usage`

Per-endpoint request counts over the trailing 30 days, plus the total.

curl https://api.hfu.digital/v1/starplan/developers/usage \
  -H 'X-API-Key: spk_…'

{
  "data": {
    "total": 1734,
    "byEndpoint": [
      { "endpoint": "/v1/starplan/courses",  "_count": 812 },
      { "endpoint": "/v1/starplan/programs", "_count": 410 }
      /* … capped at 10 entries, sorted by count desc … */
    ],
    "period": { "from": "2026-03-27T12:00:00.000Z", "to": "2026-04-26T12:00:00.000Z" }
  }
}

The /developers/* and /webhooks* routes are the only routes that record usage — they require an X-API-Key header, so the platform knows whose tally to bump. The anonymous catalog endpoints are not counted here (they are throttled per IP, not per key).

Auditing

Every state change emits a structured log line tagged audit.starplan.developer.*:

Event	When
`audit.starplan.developer.registered`	New key issued via `/register`.
`audit.starplan.developer.key_rotated`	Key replaced via `/regenerate-key`. Logs the new `apiKeyHint`.
`audit.starplan.developer.deactivated`	Account disabled via `/deactivate`.

Webhook lifecycle events (audit.starplan.webhook.created / updated / deleted) follow the same pattern — see Webhooks.

Developer accounts

POST /v1/starplan/developers/register (anonymous)

GET /v1/starplan/developers/me

POST /v1/starplan/developers/regenerate-key

POST /v1/starplan/developers/deactivate