OAuth Integration

This guide walks through registering an OAuth app and wiring up the full authorization code flow. See OAuth 2.0 for the raw endpoint reference.

1. Register your application

Log in to the hzel dashboard, navigate to Settings → Developer → OAuth Apps, and click New Application. Provide:

• A display name your users will see on the consent screen.
• One or more redirect URIs (must be https:// in production).

Or use the API directly:

curl -X POST https://api.hzel.org/api/v1/oauth/apps \
  -H "Authorization: Bearer hzel_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","redirect_uris":["https://myapp.example.com/callback"]}'

Save the client_id (a UUID) and client_secret (hzcs_…) from the response.

2. Send the user to hzel

Build the authorization URL and redirect the user’s browser:

https://api.hzel.org/api/v1/oauth/authorize
  ?client_id=<your-client-id>
  &redirect_uri=https://myapp.example.com/callback
  &response_type=code
  &state=<csrf-state>

Generate a random state value and store it in the user’s session. Verify it matches on callback.

3. Handle the callback

After the user approves, hzel redirects to your redirect_uri:

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

Exchange the code server-side (never from the browser):

curl -X POST https://api.hzel.org/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<auth_code>",
    "redirect_uri": "https://myapp.example.com/callback",
    "client_id": "<your-client-id>",
    "client_secret": "hzcs_…"
  }'

Response:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "hzrt_…"
}

4. Make API calls

Use the access_token as a Bearer token. Access tokens expire after 15 minutes — use the refresh_token to get a new one:

curl -X POST https://api.hzel.org/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "hzrt_…",
    "client_id": "<your-client-id>",
    "client_secret": "hzcs_…"
  }'

Refresh tokens rotate on each use.