# Authentication

All Welkin API requests require a Bearer token. Tokens are obtained by calling the token endpoint with your **API Client Key** and **Secret**, which are generated in the Welkin Admin panel.

> Tokens are valid for **1 hour**. Cache your token and refresh it before expiry. Requesting a new token more than **100 times per 5 minutes** will result in a 5-minute block.

## Endpoint

**POST** `/auth/token`

**Base URL:** `https://api.welkinhealth.com`

## Request

### Headers

| Header         | Value              |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |

### Body Parameters

| Parameter   | Type   | Required | Description                          |
| ----------- | ------ | -------- | ------------------------------------ |
| `secret`    | string | Yes      | API Client secret generated in Admin |
| `apiClient` | string | Yes      | API Client key generated in Admin    |

### Example Request

```http
POST https://api.welkinhealth.com/auth/token
Content-Type: application/json

{
  "secret": "your-api-client-secret",
  "apiClient": "your-api-client-key"
}
```

## Response

### 200 OK

```json
{
  "token": "eyJhbGciOiJSUzI1NiJ9...",
  "expiresAt": "2026-03-19T14:00:00Z"
}
```

| Field       | Type   | Description                                    |
| ----------- | ------ | ---------------------------------------------- |
| `token`     | string | Bearer token to use in subsequent API requests |
| `expiresAt` | string | ISO 8601 timestamp when the token expires      |

### Using the Token

Include the token in the `Authorization` header of every subsequent request:

```http
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
```

## Setting Up an API Client

1. Log in to your Welkin Admin panel
2. Navigate to **Admin → API Clients**
3. Create a new client and assign a Security Policy
4. Copy the generated **Key** and **Secret** — the secret is shown only once

> See [Core Concepts](https://github.com/welkincloud-io/welkin-developer-docs/blob/master/getting-started/core-concepts.md) for more on Security Policies and Roles.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/getting-started/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.