> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatzy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get ID Token

Authenticates a user with their email and password and returns a JWT `idToken`.

This `idToken` must be included in the `Authorization` header when calling **protected APIs**.

### 🛡️ Authorization Header Format:

```http theme={null}
Authorization: <idToken>
```

Without a valid token, protected routes will respond with a 401 Unauthorized error. This token expires after **1 hour** after which you must call `/get_id_token` again to obtain a new one.

### 🔐 Accounts with two-factor authentication

If the account has 2FA enabled, email and password alone are not enough — the request responds `401` with:

```json theme={null}
{ "error": { "error": "This account has two-factor authentication enabled. Retry this request with a `totp_code` from your authenticator app." } }
```

Retry including the six-digit code from your authenticator app:

```json theme={null}
{
  "user_email_id": "user@example.com",
  "password": "your-password",
  "totp_code": "123456"
}
```

<Warning>
  TOTP codes are single-use and rotate every 30 seconds, so a server cannot generate one. Do not
  attempt to automate this step — use the refresh token flow below instead.
</Warning>

## Staying signed in without a password

Every successful sign-in also returns a **`refreshToken`**. Send it back on its own to get a fresh
`idToken` — no password, and no two-factor code:

```json theme={null}
{ "refresh_token": "eyJjdHkiOiJKV1QiLCJlbmMi..." }
```

This is the flow to use for servers, cron jobs and CI. Two-factor authentication does not apply
here, because the second factor was already satisfied when the refresh token was issued.

**Set it up once:**

1. Sign in by hand with `user_email_id`, `password` and — if 2FA is on — a `totp_code`.
2. Store the returned `refreshToken` wherever you keep secrets.
3. From then on, call this endpoint with `refresh_token` whenever the `idToken` expires (hourly).

<Warning>
  A refresh token is valid for **30 days** from the moment it is issued, and refreshing does not
  extend it. `refreshTokenExpiresAt` in the response tells you exactly when it dies — alert on it,
  and repeat step 1 before that date. After it expires, requests fail with `401` until you sign in
  with your password again.
</Warning>

Treat a refresh token like a password: store it encrypted, never commit it. To revoke one, change
the account password or sign out everywhere, which invalidates all outstanding refresh tokens.


## OpenAPI

````yaml post /get_id_token
openapi: 3.0.0
info:
  title: Chatzy AI API
  version: 1.0.0
  description: >-
    Chatzy AI REST API for messaging, contact conversations, and agent
    interactions.
  contact:
    name: Chatzy
    url: https://chatzy.ai
    email: support@chatzy.ai
servers:
  - url: https://vevdoh3hve.execute-api.us-east-1.amazonaws.com/prod
    description: Production Server
security: []
tags:
  - name: Authentication
    description: Authentication to access the API
  - name: Contact Conversations
    description: Get contact conversations
  - name: Conversational AI Agent Interactions
    description: Interact with the conversational AI agent
  - name: Authorized iframe Access
    description: APIs for authorized iframe access
paths:
  /get_id_token:
    post:
      tags:
        - Authentication
      summary: Get ID Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Send either `user_email_id` + `password` (plus `totp_code` if
                two-factor is enabled), or `refresh_token` on its own to renew
                without a password.
              properties:
                user_email_id:
                  type: string
                  description: Required unless `refresh_token` is supplied.
                  example: user@example.com
                password:
                  type: string
                  description: Required unless `refresh_token` is supplied.
                  example: your-password
                refresh_token:
                  type: string
                  description: >-
                    Renew an ID token without a password or two-factor code. Use
                    this for unattended integrations. Cannot be combined with
                    `password`.
                  example: eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIi...
                totp_code:
                  type: string
                  description: >-
                    Six-digit code from your authenticator app. Required only if
                    the account has two-factor authentication enabled.
                  pattern: ^[0-9]{6}$
                  example: '123456'
      responses:
        '200':
          description: Successful authentication and token retrieval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Successfully retrieved ID token
                      idToken:
                        type: string
                        example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                      expiryAt:
                        type: integer
                        format: int64
                        example: 1752577991000
                      refreshToken:
                        type: string
                        description: >-
                          Returned on password sign-in only. Store it and send
                          it back as `refresh_token` to renew without a
                          password. Valid for 30 days.
                        example: eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIi...
                      refreshTokenExpiresAt:
                        type: integer
                        format: int64
                        description: >-
                          When the refresh token stops working. Re-authenticate
                          with a password before this time.
                        example: 1755169991000

````