hzel Docs

hzel supports two authentication methods: OAuth (for applications and integrations acting on behalf of users) and Personal Access Tokens (for direct programmatic access).

All authenticated requests must include a bearer token in the Authorization header:

Authorization: Bearer <your-token>

OAuth

OAuth is the recommended method for third-party applications and integrations. It lets your application act on behalf of a hzel user without handling their credentials.

OAuth authorization code flow

Loading diagram…

Before starting the flow, register your application via the API. You must be authenticated as a hzel user to do this. You can also register and manage OAuth applications from Dashboard → Developer.

Danger

The client_secret is returned only once. Store it securely and never expose it in client-side code.

POSThttps://api.hzel.org/api/v1/oauth/apps

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.
`Content-Type`	Required	Must be `application/json`.

Build the authorization URL and redirect the user's browser to it. Generate a cryptographically random state value per request to prevent CSRF attacks.

https://hzel.org/oauth/consent
  ?client_id=<your-client-id>
  &redirect_uri=<your-redirect-uri>
  &response_type=code
  &state=<random-state>

The redirect_uri must exactly match one of the URIs registered for your application.

Step 2 — Handle the callback

After the user approves consent, hzel redirects their browser to your redirect_uri with code and state query parameters:

https://myapp.example.com/callback?code=<code>&state=<state>

If the user denies consent, the redirect instead carries error=access_denied.

Always verify that the state matches the value you sent in Step 1 before proceeding.

The authorization code is single-use and expires after 10 minutes.

Step 3 — Exchange the code for tokens

The redirect_uri must match exactly what you used in Step 1. Access tokens expire after 15 minutes (900 seconds).

POSThttps://api.hzel.org/api/v1/oauth/token

Header	Required	Description
`Content-Type`	Required	Must be `application/json`. No `Authorization` header is used — credentials are passed in the request body.

Step 4 — Call the API

Use the access token as a bearer token on every API request. See Get current user below for a concrete example.

Step 5 — Refresh the access token

When the access token expires, exchange the refresh token for a new token pair. Refresh tokens are rotated on every use — the token you send is immediately invalidated. Always persist the latest refresh_token from the response.

POSThttps://api.hzel.org/api/v1/oauth/token

Header	Required	Description
`Content-Type`	Required	Must be `application/json`. No `Authorization` header — credentials are in the body.

Step 6 — Revoke a refresh token

Call this when a user disconnects your application or signs out. Revocation is idempotent — revoking an already-revoked token succeeds silently.

POSThttps://api.hzel.org/api/v1/oauth/token/revoke

Header	Required	Description
`Content-Type`	Required	Must be `application/json`. No `Authorization` header — credentials are in the body.

Managing your OAuth application

All app management endpoints return an OAuthApplicationView — the client_secret is never included. See the structure reference for the full field table.

GEThttps://api.hzel.org/api/v1/oauth/apps

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT. Returns only apps owned by the authenticated user.

GEThttps://api.hzel.org/api/v1/oauth/apps/{id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT. Must own the application.

PATCHhttps://api.hzel.org/api/v1/oauth/apps/{id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT. Must own the application.
`Content-Type`	Required	Must be `application/json`.

Rotating the client secret immediately revokes all existing refresh tokens for the application. Users will need to re-authorize.

POSThttps://api.hzel.org/api/v1/oauth/apps/{id}/secret

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT. Must own the application.

DELETEhttps://api.hzel.org/api/v1/oauth/apps/{id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT. Must own the application.

Public app info

This unauthenticated endpoint is used by the hzel consent page to display application identity before a user approves access.

GEThttps://api.hzel.org/api/v1/oauth/apps/public/{client_id}

Returns an OAuthAppPublicView wrapped in { "data": … }.

{
  "data": {
    "client_id": "a1b2c3d4-0000-0000-0000-000000000001",
    "name": "My Integration",
    "description": "Optional description",
    "owner_name": "Alice Example"
  }
}

Personal Access Tokens (PATs)

PATs are long-lived tokens tied directly to your account. They are best suited for CI pipelines, scripts, and other automated workflows where an interactive OAuth flow is not practical.

Warning

All three PAT endpoints reject OAuth application tokens with 403 Forbidden. Use a PAT or a browser session to manage tokens.

Create a token

Danger

The raw token value is returned only once at creation. Store it securely — if you lose it, you must revoke the token and create a new one.

POSThttps://api.hzel.org/api/v1/tokens

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. OAuth app tokens return `403 Forbidden`. Use a PAT or session token.
`Content-Type`	Required	Must be `application/json`.

List tokens

GEThttps://api.hzel.org/api/v1/tokens

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. OAuth app tokens return `403 Forbidden`. Use a PAT or session token.

Revoke a token

Revocation is immediate. In-flight requests using the revoked token are rejected. Returns 404 Not Found if the token ID does not exist.

DELETEhttps://api.hzel.org/api/v1/tokens/{token_id}

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. OAuth app tokens return `403 Forbidden`. Use a PAT or session token.

Get current user

Returns identity information about the account that owns the token used for this request. Works with all auth methods.

GEThttps://api.hzel.org/api/v1/auth/me

Header	Required	Description
`Authorization`	Required	`Bearer <token>`. Accepted auth methods: PAT, OAuth app token, JWT.

Authentication