Client Credentials
Agent Clients hold the credentials required to authenticate your client application when connecting to the agent from Serenity Star Chat Widget, or other clients.
Create a new Agent Client by following the steps below:
- Navigate to Agents and click on the agent you want to reach the Agent Design Studio page.
- Click on the Security tab.
- Click on the Create Client button.
- You will receive the Public Key, Client ID, and Client Secret.
How it works
The authentication flow works as follows:
-
Widget calls Client Token Provider — On initialization (and on every token refresh), the widget calls your Client Token Provider function, passing context information (such as channel and agent details).
-
Server Token Provider signs a Client Token — The Client Token Provider sends a token request to your Server Token Provider. Your server creates a short-lived Client Token (JWT with recommended TTL: 30–60 seconds) signed with the Client Secret, and returns it.
-
Widget exchanges the Client Token — The widget sends the Client Token to the Serenity API, which validates the signature using the associated Client Secret stored on our servers.
-
Serenity API returns an Access Token — If the Client Token is valid, the Serenity API returns an Access Token that the widget uses for all subsequent API requests via the
Authorization: Bearer {accessToken}header.
┌────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────┐
│ Widget │ │ Client Token │ │ Server Token │ │ Serenity API │
│ (browser) │ │ Provider (your code) │ │ Provider (your code) │ │ │
└─────┬──────┘ └──────────┬───────────┘ └──────────┬───────────┘ └──────┬───────┘
│ │ │ │
│ 1. call with │ │ │
│ {context} │ │ │
│──────────────────────>│ │ │
│ │ 2. POST {tokenRequest} │ │
│ │───────────────────────────>│ │
│ │ │ 3. Sign Client Token │
│ │ │ with Client Secret │
│ │ 4. Client Token (JWT) │ │
│ │<───────────────────────────│ │
│ 5. Client Token │ │ │
│<──────────────────────│ │ │
│ │
│ 6. Exchange Client Token │
│────────────────────────────────────────────────────────────────────────────>│
│ 7. Validate signature │
│ 8. Access Token │
│<────────────────────────────────────────────────────────────────────────────│
│ │
│ 9. Authorization: Bearer {accessToken} │
│────────────────────────────────────────────────────────────────────────────>│
Token Provider
To avoid exposing any sensitive information to the browser, the Agent Client relies on a token provider to generate the Client Token. The token provider consists of two components: the Client Token Provider, which runs in the client application (e.g., within the Serenity Star Chat Widget), and the Server Token Provider, which runs on your server.
Client Token Provider
The Client Token Provider is responsible for executing the request to the token provider server, and retrieving the Client Token. The goal of the Client Token Provider is to allow Serenity Star customers to freely implement the token retrieval logic, and integrate it with their own authentication system as needed.
Here's an example of how you could implement a Client Token Provider within Serenity Star Chat Widget:
const chat = new AIHubChat("aihub-chat", {
agentCode: "<Your Agent Code>",
channel: "web",
baseURL: "https://api.serenitystar.ai/api",
publicKey: "<Your Public Key>",
tokenProvider: async ({ context }) => {
const response = await fetch("https://your-server.com/auth/serenity-token", {
method: "POST",
headers: { "Content-Type": "application/json", "Authorization": `<if needed, add your server's authorization token here>` },
body: JSON.stringify({ /* pass any necessary context information here as needed */ }),
});
const { token } = await response.json();
return token; // Returns the Client Token (signed JWT)
},
});
chat.init();
See the Serenity Star Chat Widget documentation for more details on how to implement the Client Token Provider.
Server Token Provider
The Server Token Provider receives the request from the Client Token Provider, and is responsible for generating the Client Token, which is a JWT that contains the necessary claims to authenticate the client application and is signed with the Client Secret provided when creating the Agent Client.
You're free to implement the Server Token Provider in any way you see fit, as long as it returns a valid Client Token when requested, with the following requirements:
- The Client Token must be a valid JWT.
- The payload should include the following claims:
sub: A unique identifier for the user. If the user is not authenticated, you can use a random unique identifier such as a UUID.iss: The Client ID provided when creating the Agent Client.
- The Client Token must be signed using the Client Secret provided when creating the Agent Client.
Here's an example of how you could implement a Server Token Provider using .NET and the System.IdentityModel.Tokens.Jwt library:
[Authorize] // The endpoint could be protected with any authentication scheme you have in place.
[HttpPost]
public IActionResult GenerateToken([FromBody] TokenRequest request)
{
string clientId = Environment.GetEnvironmentVariable("CLIENT_ID");
string clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET"); // You can also retrieve the credentials from a secure vault or from your database.
var now = DateTimeOffset.UtcNow;
SymmetricSecurityKey key = new(Encoding.UTF8.GetBytes(clientSecret));
SigningCredentials creds = new(key, SecurityAlgorithms.HmacSha256);
var claims = new[]
{
new Claim(JwtRegisteredClaimNames.Sub, request.Identity),
};
var token = new JwtSecurityToken(
issuer: clientId,
claims: claims,
notBefore: now.UtcDateTime,
expires: now.AddSeconds(60).UtcDateTime, // Short-lived token (60 seconds)
signingCredentials: creds
);
var jwt = new JwtSecurityTokenHandler().WriteToken(token);
return Ok(new { token });
}
API Keys vs Public Keys
- API Keys can be used to authenticate a client application to access the Serenity Star API. They can be configured to have specific permissions and access to specific Agents. Anyone with the API Key can access the API and perform actions based on the permissions granted to that key.
- Public Keys are used in conjunction with the Client ID and Client Secret to authenticate a client application. They don't grant access to the API nor hold any permissions on their own.