Skip to main content

Developers

API Authentication

To call the HacknPlan API, requests must be both authenticated (identity) and authorized (permissions).

API keys

HacknPlan currently uses API keys as the authentication method.

An API key is a long token linked to your user account. You generate keys from your user settings:

Avatar -> Settings -> API -> Create

Provide a clear label for each key (for example, CI sync script or internal dashboard) so keys are easy to audit and revoke.

Scopes

When creating a key, you choose scopes that define what the key can do.

Available scopes:

  • Workspaces Read
  • Workspaces Admin
  • Projects Read
  • Projects Admin
  • Work Items Read
  • Work Items Write
  • Design Model Read
  • Design Model Write

Scopes and project permissions are both enforced. A call is allowed only when:

  • the key has the required scope, and
  • the underlying user has sufficient permissions in that workspace/project

Using the API key

After scope selection, generate the key and store it securely.

Important: the full key value is shown only once at creation time.

Send it in the Authorization header:

  • Header: Authorization
  • Value: ApiKey YOUR_API_KEY

Example:

const response = await fetch("https://api.hacknplan.com/v0/projects", {
  method: "GET",
  headers: {
    Authorization: "ApiKey " + YOUR_API_KEY,
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

Revoking API keys

API keys do not expire automatically. Revoke keys when they are no longer needed or if compromise is suspected.

Path: Settings -> API -> Revoke

After revocation, requests using that key are rejected.