Authentication
You'll need to authenticate your requests to access any of the endpoints in the Utopian Labs API. In this guide, we'll look at how authentication works. Utopian Labs uses API keys to authenticate your API requests.
API Key Authentication
To authenticate with the Utopian Labs API, you'll need an API key that starts with sk_
. You can find your API key in the Utopian Labs dashboard under API settings.
Authentication Examples
curl https://api.utopianlabs.ai/v1/endpoint \
-H "Authorization: Bearer your_api_key_here"
Webhook Signing & Verification
Utopian Labs signs webhook payloads using a signing secret unique to your organization. This allows you to verify that incoming webhook requests are authentic and have not been tampered with.
When a webhook is sent to your callback URL, it includes a JWT signature in the X-Signature
header. You should verify this signature using your signing secret, which you can find in the Utopian Labs Portal.
How it works
- Each organization has a unique signing secret.
- When a webhook is triggered, Utopian Labs signs the payload with this secret and includes a JWT in the
X-Signature
header. - You should verify this JWT using your secret to ensure authenticity.
Step-by-step: Verifying Webhook Signatures
1. Get your signing secret
Go to the Utopian Labs Portal and copy your organization's signing secret.
2. Receive a webhook
When your callback URL is called, the request will include:
- The webhook payload (in the body)
- The
X-Signature
header (a JWT)
3. Verify the JWT signature
You must verify the JWT using your signing secret. The JWT is signed with the HS256 algorithm and includes the id
of the agent run as a claim.
Note: Signatures are only included if you have generated a signing secret in the portal. If you have not generated a secret, the
X-Signature
header will not be present.
The decoded JWT will look like this:
{
"id": "abc123",
"iat": 1710000000,
"exp": 1710000300
}
Below are code examples for verifying the signature in different languages:
Webhook Signature Verification Examples
import { Request, Response } from "express";
import jwt from "jsonwebtoken";
export const webhookHandler = (req: Request, res: Response) => {
const signature = req.headers["x-signature"] as string | undefined;
if (!signature) return res.status(400).send("Missing signature");
const signingSecret = process.env.UTOPIAN_SIGNING_SECRET!;
try {
const decoded = jwt.verify(signature, signingSecret, { algorithms: ["HS256"] }) as { id: string };
// decoded.id contains the ID of the run
console.log("Verified webhook for run:", decoded.id);
res.status(200).send("OK");
} catch (err) {
res.status(401).send("Invalid signature");
}
};
Notes
- Always keep your signing secret safe. Rotate it here if you suspect it has been compromised.
- The JWT expires after 5 minutes for security.
- If verification fails, reject the webhook request. The Utopian Labs API will automatically try the callback again.