# Mint a patient RTC token

Operation ID: `telehealth.createPatientToken`

Mint an Agora RTC token that lets the calling patient join the given `channel_id` as a subscriber. The caller's Bearer JWT must resolve to the patient Cognito pool; a token from any other pool is rejected.

## Public method

`createPatientToken`

Signature: `telehealth.createPatientToken(request)`

Return type: `Promise<TelehealthTokenResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /telehealth/tokens/patient`

## Path parameters

None.

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`CreatePatientTokenRequest`](../models/CreatePatientTokenRequest.md) | Yes |  |  |  | No |  |

Request model: [`CreatePatientTokenRequest`](../models/CreatePatientTokenRequest.md)

## Request example

```json
{
  "channel_id": "hc-00000000000000000000000000000000",
  "uid": 1001
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `200` | [`TelehealthToken`](../models/TelehealthToken.md) | application/json | Patient RTC token minted successfully |

## Success response examples

### 200

```json
{
  "app_id": "00000000000000000000000000000000",
  "channel_id": "hc-00000000000000000000000000000000",
  "expires_at": "2026-01-01T10:00:00Z",
  "role": "patient",
  "rtc_token": "EXAMPLE-AGORA-RTC-TOKEN-0000000000000000000000000000000000",
  "ttl_seconds": 3600,
  "uid": 1001
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`telehealth.ErrorResponse`](../models/telehealth.ErrorResponse.md) | application/json | The request body failed validation, or the Agora service is not configured |
| `401` | [`telehealth.ErrorResponse`](../models/telehealth.ErrorResponse.md) | application/json | Authentication required — missing or invalid Bearer JWT |
| `403` | [`telehealth.ErrorResponse`](../models/telehealth.ErrorResponse.md) | application/json | Authenticated caller is not from the patient Cognito pool |

## Error examples

### 400 — Agora credentials are not configured for this environment

```json
{
  "error": "AGORA_APP_ID and AGORA_APP_CERTIFICATE are required"
}
```

### 400 — The request body is missing a required field

```json
{
  "error": "1 validation error for CreateTelehealthTokenRequest\nchannel_id\n  Field required [type=missing, input_value={'uid': 1}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.13/v/missing"
}
```

### 401 — No Authorization header was supplied

```json
{
  "error": "Missing Authorization header"
}
```

### 403 — Caller authenticated from the provider pool instead of patient

```json
{
  "error": "Patient token requires patient pool type, got provider"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { CreateTelehealthTokenRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "channel_id": "hc-00000000000000000000000000000000",
  "uid": 1001
};

const result = await telehealth.createPatientToken(request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"channel_id":"hc-00000000000000000000000000000000","uid":1001}' \
  'https://dev-api-telehealth.health.cloud/telehealth/tokens/patient'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.