Authentication and API keys

How the API authenticates

Asgard authenticates with the X-API-KEY header. Every API request has to carry a valid API key.

Request header

POST /generic/ns/{namespace}/bot-provider/{bot_provider_name}/message/sse
Content-Type: application/json
X-API-KEY: your-api-key-here

Getting an API key

1. Sign in to the Asgard platform
2. Open the project you want
3. Go to Integration > App
4. Create a new API key, or copy an existing one

Keep the key private

An API key is a credential. Do not put it in front-end code, in version control, or anywhere public.

LLM provider API keys

Asgard works with several LLM providers, and you configure the relevant API key on the platform:

Provider	What it covers	Documentation
OpenAI	The GPT-4 and GPT-3.5 families	OpenAI API Keys
Azure AI	Azure OpenAI Service	Azure Portal
Anthropic	The Claude family	Anthropic Console
Mistral	The Mistral family	Mistral Platform
Gemini	The Google Gemini family	Google AI Studio
Voyage	Embedding models	Voyage AI

Configuring one

1. Go to AI Brain > Completion Model or Embedding Model
2. Choose the provider
3. Enter its API key and endpoint (Azure needs an extra setting)
4. Test the connection to confirm it is right

For the detailed steps see completion model settings and embedding model settings.

Authenticating from the SDK

JavaScript SDK (@asgard-js/core)

import { AsgardServiceClient } from '@asgard-js/core';

const client = new AsgardServiceClient({
  botProviderEndpoint:
    'https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}',
  apiKey: 'your-api-key', // read this from an environment variable
});

There are two ways to carry the credential. Direct Connect passes apiKey straight through; Backend Relay and custom authentication use customHeaders instead, for example Authorization: Bearer <token>. See the JavaScript SDK guide.

React SDK (@asgard-js/react)

React uses the <Chatbot> component, with the credential in config:

import { Chatbot } from '@asgard-js/react';
import '@asgard-js/react/style';

function App() {
  return (
    <Chatbot
      config={{
        botProviderEndpoint:
          'https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}',
        apiKey: process.env.REACT_APP_ASGARD_API_KEY, // read this from an environment variable
      }}
      customChannelId="user-123"
    />
  );
}

Keeping it safe

Environment variables

Keep the API key in an environment variable rather than hard-coding it:

# .env
ASGARD_API_KEY=your-api-key-here

const apiKey = process.env.ASGARD_API_KEY;

Proxy through your back end

In production, forward the API request through a back-end service so that the API key never reaches the front end:

Key rotation

Replace the API key regularly to reduce the risk:

1. Create a new API key on the Asgard platform
2. Update the key in the application
3. Once the new key is working, disable the old one

Rate limits

Limit	Value
API request rate	5 requests/sec per endpoint
Maximum execution time	3 minutes per request
Maximum steps	30 per request

For the rest, see quotas and limits.

Next

• Send Message API — the endpoint in full
• Overview and choosing a pattern — the four integration patterns compared
• JavaScript SDK — installing the front-end SDK and going further with it
• Backend SDK — the back-end SDK for Backend Relay
• Code examples — the integrations that come up most often