Authentication

Introduction

Welcome to Robofy, an AI agent platform for lead capture, customer support, and booking. This guide provides a step-by-step walkthrough to help you create your account, get your API key, and understand API Authentication in a few minutes.

By the end of this guide, you will have:

Created a Robofy account and obtained your API key.

Understood how to authenticate Robofy API requests.

Learned how to access APIs.

Understood basic error handling and security best practices.

Prerequisites

Before you begin, ensure you have the following:

A Robofy account. If you don't have one, you can create one for free.

Your Robofy API key, which can be found inside your Robofy dashboard.

API Fundamentals

Base URL

All API requests should be made to the following base URL:

https://agents.robofy.ai

Robofy provides two distinct ways to authenticate with our APIs, depending on where your code is running.

To ensure the security of your account, you must choose the correct authentication method:

Server-to-Server: For backend services (using your permanent API Key). This will work for all APIs.

Client-to-Server: For web browsers and mobile apps for (using a temporary JWT via Handshake). This will work only for the chat response–related API endpoints and used for streaming responses.

1. Server-to-Server (API Key)

Best for: Custom backends, CRM integrations, Webhooks, and internal tools.

For backend integrations where your code is secure and hidden from users, authenticate your API requests using your primary Robofy API Key.

Pass the API key in the Authorization header of your HTTP request as a Bearer token.

Example Header:

2. Client-to-Server (JWT Handshake)

Best for: Custom web chat widgets, mobile apps, and frontend Single Page Applications (SPAs).

When building custom UI components that communicate directly with Robofy from a user's browser or device, you cannot use your primary API key. Instead, you must use our Handshake API to generate a short-lived, secure JSON Web Token (JWT).

The Handshake Flow

Step 1: Generate the JWT
Before starting a chat, your client application calls the Handshake endpoint using your public Agent identifiers.

Success Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5c...",
  "expiresIn": 3600
}

Step 2: Authenticate Chat Requests
You can now use the generated JWT to authenticate calls to the /chat endpoints. Pass this token in the Authorization header.

Step 3: Handle Token Expiration
JWT tokens generated via the handshake are valid for exactly 1 hour.

If a user keeps their chat window open for longer than an hour, your client application must track the time and call the Handshake API again to fetch a new token before the current one expires. If you attempt to use an expired token, the API will return a 401 Unauthorized error.

Error Codes

If authentication fails, the Robofy API will return one of the following errors:

Status Code	Description	Resolution
`401 Unauthorized`	Missing or invalid API Key / JWT.	Check your headers and ensure the Bearer token is formatted correctly.
`401 Token Expired`	The JWT has surpassed its 1-hour lifespan.	Call the Handshake API to generate a new token.
`403 Forbidden`	The provided key lacks permission for this action.	Verify that you are using the correct API key for the environment.

Authentication

Introduction#

Prerequisites#

API Fundamentals#

Base URL#

Authentication#

1. Server-to-Server (API Key)#

2. Client-to-Server (JWT Handshake)#

The Handshake Flow#

Error Codes#

Introduction

Prerequisites

API Fundamentals

Base URL

Authentication

1. Server-to-Server (API Key)

2. Client-to-Server (JWT Handshake)

The Handshake Flow

Error Codes