Skip to content
Module 9API Authentication & Core Endpoints

Authentication and Security

The raia API lets you interact with your AI agent programmatically. Because agents can execute functions and access proprietary knowledge, authentication depends on the operation: agent operations use Agent-Secret-Key, and organization operations use Organization-Secret-Key. Keep both keys on your backend.

Setting Up API Access

  1. Open the Launch Pad for your agent
  2. Go to the Skills tab

Open Agents, choose your agent, then open Skills. These views locate the navigation; follow the skill-specific settings below.

In Launch Pad, open Agents and choose the agent you want to configure.
  1. Highlight 1: Agents
On that agent, open Skills.
  1. Highlight 1: Skills
  1. If API is not on the agent yet, use Add skill and select + on the API card. Then select Edit (pencil) on the API card. Adding the skill does not create a key.

Worked example

The examples use fictional data. Follow the same checks with approved, non-sensitive information for your own task.

If API is not on the agent yet, open Add skill and select + on the API card.

API in Add skill, before adding.
  1. Highlight 1: + (add API)

Once added, select Edit (pencil) on the API card. Adding the skill does not create a key.

Added API card.
  1. Highlight 1: Edit (pencil)
  1. Select Create API Key, enter a Name, choose an Expiration date, then select Create key. The full key is shown once: copy it into a private password manager or secret store before you select Done.

Worked example

The examples use fictional data. Follow the same checks with approved, non-sensitive information for your own task.

With no keys yet, the list is empty. Select Create API Key.

API skill with no keys yet.
  1. Highlight 1: Create API Key
  2. Highlight 2: No API keys yet

Enter a Name that identifies where the key will be used and choose an Expiration date, then Create key. Choose a lifetime that fits your team’s policy and plan how to replace the key before it expires.

Enter a Name and choose an Expiration date before Create key.
  1. Highlight 1: Name
  2. Highlight 2: Expiration date
  3. Highlight 3: Create key

The full key is shown once with Save your key now - it will never be shown again. Copy it into a private password manager or secret store before you select Done. Never share the key in chat, documentation or screenshots.

Store the one-time key privately before Done.
  1. Highlight 1: Save your key now - it will never be shown again.
  1. After Done, the key list shows only a masked preview and cannot reveal the key again. For revoking and replacing keys, see the API skill and browser extension guides.

Worked example

The examples use fictional data. Follow the same checks with approved, non-sensitive information for your own task.

After Done, the list shows only a masked Key preview with Status, Expires and Created. It cannot reveal the full key again; if you lost it, create a new key and revoke the old one.

The key list shows a masked preview, not the full secret.
  1. Highlight 1: Key preview (masked)
  2. Highlight 2: Active
  3. Highlight 3: Revoke

To stop using a key, select Revoke and reopen the list to check Revoked. Update the application’s stored credential if it needs a replacement, and check that a request using the old key is refused. Use the documented API reference for the request and authentication header.

A revoked key remains listed with its Revoked status.
  1. Highlight 1: Revoked key status
  2. Highlight 2: Delete (only remaining action)

For an authorized authentication check, send the documented agents/by-api-key request from your backend with the intended agent’s key. If it returns HTTP 403 (INVALID_CREDENTIALS), check the header, agent, expiration and revocation status without logging the secret. After revoking a key, confirm Revoked in the list and check that subsequent requests are refused; update approved clients with a replacement key when needed.

  1. Pass the required key in the matching operation’s request header from your backend, never from public browser code.

Authentication Header

curl -X POST https://api.raia2.com/external/conversations \
  -H "Content-Type: application/json" \
  -H "Agent-Secret-Key: YOUR_AGENT_SECRET_KEY" \
  -d '{ "conversationUserId": "YOUR_CONVERSATION_USER_ID" }'

Illustrative example, checked against the published OpenAPI schema — not a live successful request. Use a real conversationUserId from your own agent.

Recovery: If authentication fails, confirm the required key type in the API reference and check the selected agent or organization. Revoke an exposed key through the approved account procedure. This lesson does not verify key scope or revocation behavior.

Core API Endpoints

MethodEndpointPurpose
POST/external/conversationsCreate a new conversation. Requires conversationUserId; optional title (max 255 chars) and context (string).
POST/external/conversations/{id}/messagesSend a message to an existing conversation thread. Requires message; optional context and files.
GET/external/conversations/{id}Retrieve conversation details and metadata (no messages property).
GET/external/conversations/{id}/messagesRetrieve the conversation's saved messages array (transcript/history).
POST/external/conversations/startOutbound only: contacts a recipient over email, SMS or voice. Requires an authorized channel/account — not for ordinary web chat.
GET/external/agents/{id}/usersGet agent users using an Organization-Secret-Key.

Starting a Conversation with Context

When you call POST /external/conversations, you create a conversation for a conversation user and can pass optional context for the agent to use:

{
  "conversationUserId": "YOUR_CONVERSATION_USER_ID",
  "title": "Plan upgrade question",
  "context": "Enterprise customer since 2022. Currently on Pro plan. Last support ticket was about API rate limits."
}

Then send the user's first message with POST /external/conversations/{id}/messages:

{
  "message": "Hi, I need help upgrading my plan."
}

The agent can use this context so the user doesn't have to repeat it. Test with fictional data to check how your agent actually uses each field.

Outbound conversations are separate: POST /external/conversations/start contacts a recipient over email, SMS or voice (each channel has its own required fields, such as email/emailSubject or phoneNumber) and requires an authorized channel/account. It is not the way to start an ordinary web chat, and no outbound request should be sent just to try it.

Building Custom Interfaces

While raia provides native channels (Live Chat, SMS, Email, Voice), the API lets you build completely custom user interfaces while relying on raia for the intelligence.

Common custom UI patterns:

  • In-App Copilots: Embed the agent directly into your SaaS product's dashboard to help users navigate features
  • Internal Tools: Build a custom Slack bot or internal portal where employees can query HR policies or IT documentation
  • Headless E-commerce: Use the agent as a conversational search engine on a custom storefront

In this architecture, you own the frontend UI and user experience; raia handles RAG, tool calling, and LLM orchestration.

API Documentation

  • Interactive Swagger UI: https://api.raia2.com/api/external/docs
  • OpenAPI JSON (for SDK generation): https://api.raia2.com/api/external/docs/openapi.json

Rate Limits

API requests may be rate-limited. If you receive a 429 Too Many Requests response, implement exponential backoff in your retry logic.

FAQ: Can I fetch the raw vector search results via the API? The endpoints in this lesson return the agent's response, not raw search results. Check the API reference for what each endpoint returns.

Previous lessonNext lesson