Public API

# Example: Get error messages in French
curl -X GET https://iam.hanzo.ai/api/get-account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept-Language: fr"

Supported codes include `en`, `zh`, `es`, `fr`, `de`, `ja`, `ko`, and others. See [Internationalization](/docs/internationalization) for the full list.

## Machine-to-machine (M2M) authentication

M2M authentication is for services or scripts that call the API **without a user present**. Use it for:

- Backend services calling Hanzo IAM programmatically
- CLI tools using access tokens
- B2B: per-organization apps with their own client credentials
- Scheduled jobs, sync, and system integrations
- Service-to-service auth

Hanzo IAM supports M2M via:

1. **Client Credentials Grant (OAuth 2.0)** — Recommended. Use [Client ID and Client Secret](/docs/how-to-connect/oauth#client-credentials-grant) to obtain an access token.
2. **Client ID + Client Secret on each request** — Pass credentials directly (see method #2 below).

### Typical M2M use cases

- **Per-organization API access:** One application per organization; client credentials give that org’s admin-level access.
- **Tokens for downstream services:** Use Client Credentials to get tokens for CLIs or other services.
- **Service-to-service:** Backend calls the API as the application (org-admin equivalent).

## How to authenticate

### 1. Access token (user context)

Use the access token obtained after a user signs in (e.g. from the OAuth code exchange). API calls run with that user’s permissions.

#### Getting the token

The app receives the token at the end of the OAuth login flow (code + state). Issued tokens are also visible in the Hanzo IAM UI (**Tokens** page, e.g. `https://iam.hanzo.ai/tokens`).

Example (Go, iam-go-sdk):

```go
func (c *ApiController) Signin() {
    code := c.Input().Get("code")
    state := c.Input().Get("state")

    token, err := iamsdk.GetOAuthToken(code, state)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims, err := iamsdk.ParseJwtToken(token.AccessToken)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    if !claims.IsAdmin {
        claims.Type = "chat-user"
    }

    err = c.addInitialChat(&claims.User)
    if err != nil {
        c.ResponseError(err.Error())
        return
    }

    claims.AccessToken = token.AccessToken
    c.SetSessionClaims(claims)

    c.ResponseOk(claims)
}

#### Sending the token

1. **Query parameter:**

    ```shell
    /page?access_token=<The access token>

GET or POST /api/sso-logout?logoutAll=<true|false>

### Parameters

- **logoutAll** (optional): `true`, `1`, or omit → logout from all sessions and expire all tokens. `false` or `0` → current session only.

### Behavior

**Full SSO logout** (default):

- Deletes all active sessions for the user across all applications
- Expires all access tokens issued to the user
- Sends logout notifications with all session IDs and token hashes

**Session-only logout**:

- Deletes only the current session
- Preserves other active sessions and tokens
- Sends logout notification with only the current session ID

Use session-only logout when users should sign out from one device but stay signed in elsewhere.

### Authentication

The user must be authenticated. Use any of the [authentication methods](#how-to-authenticate) above.

### Example Request

```bash
# Full SSO logout (all sessions)
curl -X POST https://iam.hanzo.ai/api/sso-logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Session-level logout (current session only)
curl -X POST "https://iam.hanzo.ai/api/sso-logout?logoutAll=false" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Using session cookie
curl -X POST https://iam.hanzo.ai/api/sso-logout \
  --cookie "iam_session_id=abc123def456"

### Response

```json
{
  "status": "ok",
  "msg": "",
  "data": ""
}

## CORS

Hanzo IAM sets CORS headers so browsers can call the API from your frontend. Allowed origins include:

- Your application’s **Redirect URIs**
- The Hanzo IAM server hostname
- Configured origin in Hanzo IAM settings
- Special cases: `/oauth/token`, `/api/userinfo`, and origin `appleid.apple.com`

The server checks the request `Origin` against these; if it matches, it adds the appropriate `Access-Control-Allow-*` headers. For `OPTIONS` preflight, allowed methods include `GET`, `POST`, `OPTIONS`, `DELETE`, with credentials supported.

**To allow your app:** Add your frontend origin to the application’s **Redirect URIs** in the Hanzo IAM admin.