# RESTful authentication (/en/api-reference/api-ref/conversational-ai/authentication)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Conversational AI REST API requests require REST authentication. You can use token authentication or Basic HTTP authentication.

<CalloutContainer type="info">
  <CalloutDescription>
    Implement authentication on the server to mitigate the risk of data leakage.
  </CalloutDescription>
</CalloutContainer>

## Token authentication

Token authentication uses an RTC token generated on your server using your App ID and App Certificate. To authenticate with a token, include the `Authorization` header in each request:

```text
Authorization: agora token=<your_token>
```

### Prerequisites

Before you begin, get the following values from [Agora Console](https://console.agora.io):

* **App ID**: A unique string that identifies your project.
* **App Certificate**: A string used to generate tokens.

<CalloutContainer type="warning">
  <CalloutDescription>
    Never expose your App Certificate in client-side code or public repositories. Generate tokens on your server only.
  </CalloutDescription>
</CalloutContainer>

The Agora RESTful API only supports HTTPS with TLS 1.0, 1.1, or 1.2 for encrypted communication. Requests over plain HTTP are not supported and will fail to connect.

Tokens expire after a maximum of 86400 seconds.

### Using the Conversational AI SDK

If you already use the Conversational AI SDK in your project, use the SDK token generation utility to generate tokens. The token parameters must match the agent request:

* `channelName` must match `properties.channel`.
* `agentUid` must match `properties.agent_rtc_uid`.
* To use string UIDs, pass a string value for `agentUid` and set `enable_string_uid` to `true` in the request body.

Install the SDK for your language:

<CodeBlockTabs defaultValue="Node.js">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Node.js">
      Node.js
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Golang">
      Golang
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Node.js">
    ```bash
    npm install agora-agent-server-sdk
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Golang">
    ```bash
    go get github.com/AgoraIO-Conversational-AI/agent-server-sdk-go
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Python">
    ```bash
    pip install agent-server-sdk-python
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The following example generates a token with the Node.js SDK and uses it in the REST API `Authorization` header:

```js
const https = require('https');
const { generateConvoAIToken } = require('agora-agent-server-sdk');

// Keep these credentials on the server and never expose them to clients.
const appId = '<your_app_id>';
const appCertificate = '<your_app_certificate>';

const channelName = '<your_channel_name>';
const agentUid = '<your_agent_uid>';
const tokenExpirationInSeconds = 86400;

const token = generateConvoAIToken({
  appId,
  appCertificate,
  channelName,
  account: agentUid,
  tokenExpire: tokenExpirationInSeconds,
});

const data = JSON.stringify({
  name: '<agent_identifier>',
  pipeline_id: '<your_agents_pipeline_id>',
  properties: {
    channel: channelName,
    token,
    agent_rtc_uid: agentUid,
    remote_rtc_uids: ['<remote_user_uid>'],
    enable_string_uid: false,
  },
});

const options = {
  hostname: 'api.agora.io',
  path: `/api/conversational-ai-agent/v2/projects/${appId}/join`,
  method: 'POST',
  headers: {
    Authorization: 'agora token=' + token,
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(data),
  },
};

const req = https.request(options, (res) => {
  console.log(`Status code: ${res.statusCode}`);
  res.on('data', (d) => {
    process.stdout.write(d);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
```

### Using the token builder library

The [AgoraDynamicKey repository](https://github.com/AgoraIO/Tools/tree/master/DynamicKey/AgoraDynamicKey) provides open-source token generation libraries for multiple languages.

Install the token builder library for your language:

<CodeBlockTabs defaultValue="Node.js">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Node.js">
      Node.js
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Golang">
      Golang
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Node.js">
    ```bash
    npm install agora-token
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Golang">
    ```bash
    go get github.com/AgoraIO/Tools/DynamicKey/AgoraDynamicKey/go/src/rtctokenbuilder2
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Python">
    ```bash
    git clone https://github.com/AgoraIO/Tools.git
    cd Tools/DynamicKey/AgoraDynamicKey/python3/src
    ```
  </CodeBlockTab>
</CodeBlockTabs>

When using the token builder library, generate a combined RTC + RTM token and pass it in the `Authorization` header:

```js
const https = require('https');
const { RtcTokenBuilder, RtcRole } = require('agora-token');

const appId = '<your_app_id>';
const appCertificate = '<your_app_certificate>';
const channelName = '<your_channel_name>';
const agentUid = '<your_agent_uid>';
const tokenExpirationInSeconds = 86400;
const privilegeExpirationInSeconds = 86400;

const token = RtcTokenBuilder.buildTokenWithRtm(
  appId,
  appCertificate,
  channelName,
  agentUid,
  RtcRole.PUBLISHER,
  tokenExpirationInSeconds,
  privilegeExpirationInSeconds,
);

const options = {
  hostname: 'api.agora.io',
  path: `/api/conversational-ai-agent/v2/projects/${appId}/join`,
  method: 'POST',
  headers: {
    Authorization: 'agora token=' + token,
    'Content-Type': 'application/json',
  },
};

https.request(options).end();
```

## Basic HTTP authentication

Basic HTTP authentication uses your Agora customer ID and customer secret. Generate a Base64-encoded credential from the `customer_id:customer_secret` string, then include it in the `Authorization` header:

```text
Authorization: Basic <base64_credentials>
```

### Generate Customer ID and Customer Secret

To generate a Customer ID and Customer Secret, do the following:

1. In [Agora Console](https://console.agora.io), click the username at the bottom of the navigation sidebar to open the account menu, then select **RESTful API Keys**.

   ![RESTful API keys](https://assets-docs.agora.io/images/console/restful-api-keys.png)

2. Select **Create API Key**. A Customer ID and Customer Secret are generated.

3. Select **Download** and save the file somewhere secure — you can download it only once. In the file, **Key** is your Customer ID and **Secret** is your Customer Secret.

4. Use the Customer ID (**Key**) and Customer Secret (**Secret**) to generate a Base64-encoded credential, and pass it to the `Authorization` parameter in the HTTP request header.

### Generate an authorization header using a third-party tool

For testing and debugging, you can use a [third-party online tool](https://www.debugbear.com/basic-auth-header-generator) to quickly generate your Authorization header. Enter your Customer ID as the Username and your Customer Secret as the Password. Your generated header should look like this:

```text
Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=a
```

## Related pages

* [Overview](index)
* [Start a conversational AI agent](join)
* [Stop a conversational AI agent](leave)