Skip to main content

Client Credentials Authentication

Client credentials authentication allows API clients to authenticate using client credentials (client_id and client_secret). This method is used for server-to-server authentication.

Generate Client Auth Token​

Generate an authentication token for API clients.

Endpoint​

POST /generate-client-auth-token

Request Body​

{
  client_id: string;
  client_secret: string;
  user: {
    first_name: string;
    last_name: string;
    date_of_birth?: string;
    email?: string;
    phone?: string;
    uid?: string;
    eid?: string;
    group_name?: string; // Required if not in root
  };
}

Example Request​

curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15",
      "email": "john.doe@example.com",
      "group_name": "my-group"
    }
  }'

Try It Out

API Configuration

Client Credentials

User Information

At least one identifier required (date_of_birth, email, uid, or eid)
Required if not in root

Request Preview

{
  "client_id": "",
  "client_secret": "",
  "user": {
    "first_name": "",
    "last_name": ""
  }
}

Success Response​

{
  status: 200;
  data: {
    access_token: string; // JWT — includes domain, employee_id, and user identity claims
  }
}

Note: Use access_token for all authenticated API requests (access-token header). The embed only needs IndexHealthAI.initChat({ access_token }) — domain and employee context are read from the JWT. Mint server-side only; never put client_secret in the browser.

Eligibility binding

The supplied user must resolve to a record in your account's eligibility data. The minted access_token is bound to that user's employee_id (carried as a JWT claim) so downstream calls (e.g. sync-user) can load the right profile without a second round trip. If no eligible user matches, the request fails with 401 and no token is issued — chat will not open. auth_token is no longer returned.

Error Responses​

Missing Required Fields​

{
  status: 400;
  data: {
  }
  message: "Missing required fields: user, group_name";
}

Missing User Fields​

{
  status: 400;
  data: {
  }
  message: "Missing required user fields: first_name, last_name";
}

Missing User Identifier​

{
  status: 400;
  data: {
  }
  message: "Missing required user fields: date_of_birth or email or uid";
}

Invalid Client Credentials​

{
  status: 401;
  data: {
  }
  message: "Invalid client credentials";
}

User Not Eligible (cannot bind employee)​

{
  status: 401;
  data: {
  }
  message: "Employee could not be bound";
}

Returned when the supplied user does not match any record in your eligibility data. No token is issued.

Required Fields​

Always Required​

  • client_id - Client identifier
  • client_secret - Client secret
  • user - User object

User Object Required Fields​

  • first_name - User's first name
  • last_name - User's last name
  • At least one of:
    • date_of_birth - User's date of birth
    • email - User's email address
    • uid or eid - User unique identifier

Optional User Fields​

  • phone - User's phone number
  • group_name - Tenant/group identifier (required if not in root)

Next Steps​

After receiving an access token:

  1. Use access_token for all authenticated API requests
  2. Include it in the access-token request header (the domain is read from the token's claims)
  3. For the chat embed, just call IndexHealthAI.initChat({ access_token })
  4. Store the token securely on the client side; it is a per-session credential