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

# Authenticate with the Hello Clever API

> Learn how to include your app-id and secret-key on every Hello Clever API request, and when the v1 payment gateway link needs an additional access token.

Every request to the Hello Clever API, across the v1, v2, v3, Card, and Cashback APIs, is authenticated with two headers: `app-id` and `secret-key`. One endpoint, the v1 hosted payment gateway link, additionally requires a short-lived access token generated from those same credentials. This page shows you how to get your credentials and use them correctly.

## Before you start

You need an active Hello Clever merchant account before you can generate credentials. Follow the [Integration Keys](/integration-keys) guide to create a Payments Account and retrieve your `app-id` and `secret-key`.

## Authenticate your requests

Include your `app-id` and `secret-key` as headers on every request:

<ParamField header="app-id" type="string" required>
  Your application identifier, issued from the Hello Clever Merchant Dashboard.
</ParamField>

<ParamField header="secret-key" type="string" required>
  The secret key associated with your `app-id`. Never expose this in client-side code.
</ParamField>

```bash Example request theme={null}
curl --request GET \
  --url https://api.cleverhub.co/api/v2/payins/payin_methods \
  --header 'app-id: YOUR_APP_ID' \
  --header 'secret-key: YOUR_SECRET_KEY'
```

This header pair authenticates every endpoint across the [v1](/api/v1/introduction), [v2](/api/v2/introduction), [v3](/api/v3/introduction), [Card](/api/card/overview), and [Cashback](/api/cashback/overview) APIs, with one exception described below.

<Note>
  Use the sandbox base URL and sandbox credentials when developing or testing. Switch to the production base URL and credentials only when you are ready to go live. See the [API overview](/api/overview#base-urls) for the base URL of each API version.
</Note>

## Special case: v1 payment gateway link access token

Creating a hosted payment gateway link with `POST /v1/payment_gateways/create_payment` requires an additional `access-token` header. Generate one by calling the access token endpoint with your `app-id` and `secret-key` headers:

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url https://api-merchant.helloclever.co/api/v1/payment_gateways/access_token \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "access_token": "eyJhbGciOi...",
    "expires_in": 3600
  }
  ```
</CodeGroup>

Pass the returned value in the `access-token` header when you create the payment gateway link:

```bash theme={null}
curl --request POST \
  --url https://api-merchant.helloclever.co/api/v1/payment_gateways/create_payment \
  --header 'access-token: eyJhbGciOi...' \
  --header 'Content-Type: application/json' \
  --data '{ ... }'
```

`expires_in` is in seconds: the token is valid for 3600 seconds (1 hour). When it expires, request a new one and retry. You only need this token for the payment gateway link endpoint; every other v1 endpoint continues to use your `app-id` and `secret-key` headers directly. Refer to the [v1 API reference](/api/v1/introduction) for full details on the payment gateway link endpoints.

## Security best practices

<Warning>
  Never embed your `secret-key` in client-side code, mobile apps, or any publicly accessible location. It must remain on your server at all times.
</Warning>

* **Store credentials in environment variables or a secrets manager**, not in source code or configuration files checked into version control.
* **Rotate your `secret-key` periodically** to limit the blast radius of a potential leak.
* **Use HTTPS for all API calls** to ensure credentials are transmitted over an encrypted connection.
* **Scope access** by creating separate Payments Accounts (and therefore separate credentials) for different environments, currencies, or applications.
* **Monitor for unexpected usage** in the Merchant Dashboard to detect potential credential misuse early.
* **Don't confuse `secret-key` with your Webhook Secret Key.** Your `secret-key` authenticates outgoing requests you make to the Hello Clever API. Your Webhook Secret Key is a separate credential Hello Clever uses to sign incoming webhook payloads sent to your server. See [Webhooks](/api/webhooks) for how to verify it.


## Related topics

- [Hello Clever API Overview](/api/overview.md)
- [Hello Clever API Security Best Practices](/security/api-security.md)
- [Hello Clever Platform Overview](/platform-overview/overview.md)