> For the complete documentation index, see [llms.txt](https://help.tahua.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tahua.io/knowledge-base/integrations-help-guides/api-access/using-the-api.md).

# Using the API

## How to authenticate and make requests to the Tahua API.

### Getting an access token

Tahua uses the OAuth 2.0 **Client Credentials** grant type. To get an access token, send a POST request to your organisation's token endpoint:

```
POST https://<your-subdomain>.tahua.io/oauth/token
```

With the following parameters:

| Parameter       | Value                |
| --------------- | -------------------- |
| `grant_type`    | `client_credentials` |
| `client_id`     | Your Client ID       |
| `client_secret` | Your Client Secret   |

#### Example request

```bash
curl -X POST https://your-org.tahua.io/oauth/token \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'
```

#### Example response

```json
{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 432000,
  "created_at": 1717804800
}
```

### Making API requests

Include the access token in the `Authorization` header of each request:

```bash
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-org.tahua.io/funding_system/api/v2/endpoint
```

### Token expiry

Access tokens expire after **5 days**. When a token expires, request a new one using the same client credentials. Your application should handle `401 Unauthorized` responses by requesting a fresh token.

### Security best practices

* Store your Client ID and Client Secret in environment variables or a secrets manager — never commit them to source control.
* Use a separate API credential for each integration so you can revoke access independently.
* Delete credentials that are no longer in use.