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

LLM provider API keys​

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

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​

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