Authentication

Hanzo Commerce uses Hanzo ID for authentication, providing OAuth2-based access control with support for multiple authentication flows.

Overview

Hanzo ID supports the following OAuth2 grant types:

Client Credentials: For server-to-server API access

Authorization Code: For user-facing applications

Refresh Token: For maintaining long-lived sessions

Client Credentials Flow

Use this flow for backend services that need API access without user interaction.

Obtain Client Credentials

Request an Access Token

curl -X POST https://api.hanzo.ai/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "grant_type": "client_credentials"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the Access Token

Include the token in your API requests:

curl https://api.hanzo.ai/order \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Authorization Code Flow

Use this flow for applications where users authenticate directly.

Redirect to Authorization

https://id.hanzo.ai/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=read write&
  state=random_state_string

Handle the Callback

After user authorization, Hanzo ID redirects to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_string

Exchange Code for Tokens

curl -X POST https://api.hanzo.ai/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "code": "AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Refresh Tokens

When an access token expires, use the refresh token to obtain a new one:

curl -X POST https://api.hanzo.ai/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "grant_type": "refresh_token"
  }'

User Management

Create a User Account

curl -X POST https://api.hanzo.ai/account/create \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure_password",
    "firstName": "John",
    "lastName": "Doe"
  }'

curl -X POST https://api.hanzo.ai/account/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure_password"
  }'

Password Reset

# Request reset
curl -X POST https://api.hanzo.ai/account/reset \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

# Complete reset with token from email
curl -X POST https://api.hanzo.ai/account/reset/confirm \
  -H "Content-Type: application/json" \
  -d '{
    "token": "RESET_TOKEN",
    "password": "new_secure_password"
  }'

Access Control

Scopes

Control API access with scopes:

Scope	Description
`read`	Read-only access to resources
`write`	Create and update resources
`admin`	Full administrative access
`orders:read`	Read orders only
`orders:write`	Create and manage orders
`products:write`	Manage product catalog

Middleware Integration

In Go applications, use the access token middleware:

import "github.com/hanzoai/commerce/middleware"

router.Use(middleware.AccessToken())

// Protected route
router.GET("/orders", func(c *gin.Context) {
    // Access token is validated
    user := middleware.GetUser(c)
    // ...
})

Security Best Practices

Never expose your client_secret in client-side code. Use the Authorization Code flow with PKCE for browser applications.

Store secrets securely: Use environment variables or secret management services

Use HTTPS: Always use encrypted connections

Validate tokens: Verify token signatures and expiration

Implement token rotation: Regularly refresh access tokens

Limit scopes: Request only the permissions you need

On this page