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.

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:

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.