Authentication Setup

Security Architecture

Why Token Provider?

Your organization’s API key never touches the browser for security reasons:

API Key Protection: Your Animus API key stays secure on your backend
User Authentication: You control who can access your AI services
Token Expiration: JWT tokens automatically expire for enhanced security
Audit Trail: Track usage through your own authentication system

Authentication Flow

Backend Implementation

Basic Token Provider Endpoint

Here’s how to implement a secure token provider endpoint in different backend frameworks:

// server.js
const express = require('express');
const cors = require('cors');
const app = express();

app.use(cors());
app.use(express.json());

// Your Animus API key (keep this secure!)
const ANIMUS_API_KEY = process.env.ANIMUS_API_KEY;

app.post('/api/get-animus-token', async (req, res) => {
  try {
    // 1. Authenticate your user (implement your own logic)
    const userToken = req.headers.authorization;
    if (!userToken || !isValidUserToken(userToken)) {
      return res.status(401).json({ error: 'Unauthorized' });
    }

    // 2. Call Animus Auth Service
    const response = await fetch('https://api.animusai.co/auth/generate-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'apikey': ANIMUS_API_KEY
      }
    });

    if (!response.ok) {
      throw new Error(`Animus auth failed: ${response.status}`);
    }

    const data = await response.json();

    // 3. Return only the JWT token
    res.json({
      accessToken: data.accessToken
    });

  } catch (error) {
    console.error('Token generation error:', error);
    res.status(500).json({ error: 'Failed to generate token' });
  }
});

// Your user authentication logic
function isValidUserToken(token) {
  // Implement your authentication logic here
  // This could check JWT tokens, session cookies, API keys, etc.
  return token === 'Bearer valid-user-token'; // Simplified example
}

app.listen(3001, () => {
  console.log('Token provider server running on port 3001');
});

from flask import Flask, request, jsonify
from flask_cors import CORS
import requests
import os

app = Flask(__name__)
CORS(app)

ANIMUS_API_KEY = os.getenv('ANIMUS_API_KEY')

@app.route('/api/get-animus-token', methods=['POST'])
def get_animus_token():
    try:
        # 1. Authenticate your user
        auth_header = request.headers.get('Authorization')
        if not auth_header or not is_valid_user_token(auth_header):
            return jsonify({'error': 'Unauthorized'}), 401

        # 2. Call Animus Auth Service
        response = requests.post(
            'https://api.animusai.co/auth/generate-token',
            headers={
                'Content-Type': 'application/json',
                'apikey': ANIMUS_API_KEY
            }
        )

        if not response.ok:
            raise Exception(f'Animus auth failed: {response.status_code}')

        data = response.json()

        # 3. Return only the JWT token
        return jsonify({
            'accessToken': data['accessToken']
        })

    except Exception as error:
        print(f'Token generation error: {error}')
        return jsonify({'error': 'Failed to generate token'}), 500

def is_valid_user_token(token):
    # Implement your authentication logic here
    return token == 'Bearer valid-user-token'  # Simplified example

if __name__ == '__main__':
    app.run(port=3001, debug=True)

// pages/api/get-animus-token.ts (or app/api/get-animus-token/route.ts for App Router)
import { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    // 1. Authenticate your user
    const authHeader = req.headers.authorization;
    if (!authHeader || !isValidUserToken(authHeader)) {
      return res.status(401).json({ error: 'Unauthorized' });
    }

    // 2. Call Animus Auth Service
    const response = await fetch('https://api.animusai.co/auth/generate-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'apikey': process.env.ANIMUS_API_KEY!
      }
    });

    if (!response.ok) {
      throw new Error(`Animus auth failed: ${response.status}`);
    }

    const data = await response.json();

    // 3. Return only the JWT token
    res.json({
      accessToken: data.accessToken
    });

  } catch (error) {
    console.error('Token generation error:', error);
    res.status(500).json({ error: 'Failed to generate token' });
  }
}

function isValidUserToken(token: string): boolean {
  // Implement your authentication logic here
  return token === 'Bearer valid-user-token'; // Simplified example
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"

    "github.com/gin-contrib/cors"
    "github.com/gin-gonic/gin"
)

type TokenResponse struct {
    AccessToken string `json:"accessToken"`
}

type ErrorResponse struct {
    Error string `json:"error"`
}

func main() {
    r := gin.Default()
    r.Use(cors.Default())

    r.POST("/api/get-animus-token", getAnimusToken)
    r.Run(":3001")
}

func getAnimusToken(c *gin.Context) {
    // 1. Authenticate your user
    authHeader := c.GetHeader("Authorization")
    if authHeader == "" || !isValidUserToken(authHeader) {
        c.JSON(http.StatusUnauthorized, ErrorResponse{Error: "Unauthorized"})
        return
    }

    // 2. Call Animus Auth Service
    animusAPIKey := os.Getenv("ANIMUS_API_KEY")
    
    req, err := http.NewRequest("POST", "https://api.animusai.co/auth/generate-token", bytes.NewBuffer([]byte("{}")))
    if err != nil {
        c.JSON(http.StatusInternalServerError, ErrorResponse{Error: "Failed to create request"})
        return
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("apikey", animusAPIKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        c.JSON(http.StatusInternalServerError, ErrorResponse{Error: "Failed to generate token"})
        return
    }
    defer resp.Body.Close()

    var tokenResp TokenResponse
    if err := json.NewDecoder(resp.Body).Decode(&tokenResp); err != nil {
        c.JSON(http.StatusInternalServerError, ErrorResponse{Error: "Failed to parse response"})
        return
    }

    // 3. Return only the JWT token
    c.JSON(http.StatusOK, tokenResp)
}

func isValidUserToken(token string) bool {
    // Implement your authentication logic here
    return token == "Bearer valid-user-token" // Simplified example
}

Frontend Integration

Basic SDK Configuration

Once your backend is set up, configure the SDK to use your token provider:

import { AnimusClient } from 'animus-client';

const client = new AnimusClient({
  tokenProviderUrl: 'https://your-backend.com/api/get-animus-token',
  chat: {
    model: 'vivian-llama3.1-70b-1.0-fp8',
    systemMessage: 'You are a helpful assistant.'
  }
});

// The SDK will automatically call your token provider when needed
client.chat.send("Hello!"); // Event-driven - listen for messageComplete event

User Authentication Integration

The SDK doesn’t have built-in user authentication features. Instead, you handle user authentication in your backend token provider endpoint. Here’s the recommended pattern:

// Your backend handles user authentication
// The SDK only needs the token provider URL
const client = new AnimusClient({
  tokenProviderUrl: 'https://your-backend.com/api/get-animus-token',
  chat: {
    model: 'vivian-llama3.1-70b-1.0-fp8',
    systemMessage: 'You are a helpful assistant.'
  }
});

// Your backend endpoint should:
// 1. Validate the user's session/token
// 2. Only return Animus tokens for authenticated users
// 3. Return 401 for unauthenticated requests

Managing User Sessions

Since the SDK doesn’t handle user authentication directly, you’ll need to manage user sessions at the application level:

class AuthenticatedApp {
  private client: AnimusClient | null = null;
  private userSession: string | null = null;

  constructor() {
    // Initialize without client
  }

  async login(userCredentials: any) {
    // Handle user login with your auth system
    this.userSession = await this.authenticateUser(userCredentials);
    
    // Create SDK client after successful login
    // Your backend will validate the session when SDK requests tokens
    this.client = new AnimusClient({
      tokenProviderUrl: 'https://your-backend.com/api/get-animus-token',
      chat: {
        model: 'vivian-llama3.1-70b-1.0-fp8',
        systemMessage: 'You are a helpful assistant.'
      }
    });
  }

  async sendMessage(message: string) {
    if (!this.client || !this.userSession) {
      throw new Error('User not authenticated');
    }
    // Use event-driven approach
    this.client.chat.send(message);
    // Listen for messageComplete event to get response
  }

  logout() {
    this.userSession = null;
    if (this.client) {
      this.client.clearAuthToken(); // Clear cached Animus token
    }
    this.client = null;
  }

  private async authenticateUser(credentials: any): Promise<string> {
    // Your user authentication logic here
    // Return session token/ID
    return 'user-session-token';
  }
}

// Usage
const app = new AuthenticatedApp();

// User login
await app.login({ username: 'user', password: 'pass' });
const response = await app.sendMessage("Hello!");

// User logout
app.logout();

Advanced Authentication

Custom Token Storage

Control where Animus tokens are stored in the browser:

const client = new AnimusClient({
  tokenProviderUrl: 'https://your-backend.com/api/get-animus-token',
  tokenStorage: 'localStorage', // Persists across browser sessions
  chat: {
    model: 'vivian-llama3.1-70b-1.0-fp8',
    systemMessage: 'You are a helpful assistant.'
  }
});

const client = new AnimusClient({
  tokenProviderUrl: 'https://your-backend.com/api/get-animus-token',
  tokenStorage: 'sessionStorage', // Default - cleared when tab closes
  chat: {
    model: 'vivian-llama3.1-70b-1.0-fp8',
    systemMessage: 'You are a helpful assistant.'
  }
});

Token Refresh Handling

Token refresh happens automatically, but you can handle authentication errors:

import { AuthenticationError } from 'animus-client';

try {
  // Event-driven approach - no await needed
  client.chat.send("Hello!");
  
  // Or use completions() for direct API calls
  const response = await client.chat.completions({
    messages: [{ role: 'user', content: 'Hello!' }]
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Token might be expired or invalid
    // Your backend token provider may have rejected the request
    console.log('Authentication failed, redirecting to login...');
    redirectToLogin();
  }
}

Manual Token Management

Clear the stored Animus token when needed:

// Clear stored Animus token (forces refresh on next request)
client.clearAuthToken();

// Next request will call your token provider again
client.chat.send("This will fetch a new token");

Note: The SDK doesn’t provide methods to check if a token exists or inspect token details. Token management is handled automatically, and you only need to clear tokens when necessary (e.g., on user logout).

CORS Configuration

Configure CORS properly for production:

// Production CORS setup
app.use(cors({
  origin: ['https://your-app.com', 'https://www.your-app.com'],
  credentials: true,
  methods: ['POST'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

from flask_cors import CORS

# Production CORS setup
CORS(app, 
     origins=['https://your-app.com', 'https://www.your-app.com'],
     supports_credentials=True,
     methods=['POST'],
     allow_headers=['Content-Type', 'Authorization'])

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/api/get-animus-token',
        headers: [
          {
            key: 'Access-Control-Allow-Origin',
            value: 'https://your-app.com',
          },
          {
            key: 'Access-Control-Allow-Methods',
            value: 'POST',
          },
          {
            key: 'Access-Control-Allow-Headers',
            value: 'Content-Type, Authorization',
          },
        ],
      },
    ];
  },
};

Troubleshooting

Common Issues

Token Provider URL Not Found (404)

// Ensure your backend endpoint is correct
const client = new AnimusClient({
  tokenProviderUrl: 'https://your-backend.com/api/get-animus-token', // Check this URL
});

CORS Errors

// Backend: Enable CORS for your frontend domain
app.use(cors({
  origin: 'https://your-frontend-domain.com'
}));

Authentication Loops

// Check that your backend returns the correct format
// Expected response: { "accessToken": "jwt_token_here" }

Debug Mode

Enable debug logging to troubleshoot authentication issues:

// Add debug logging to your token provider
console.log('Token request received:', {
  headers: req.headers,
  body: req.body,
  timestamp: new Date().toISOString()
});

import logging

# Add debug logging to your token provider
logging.info(f'Token request received: {request.headers}, {request.get_json()}, {datetime.now()}')

// Add debug logging to your token provider
console.log('Token request received:', {
  headers: req.headers,
  body: req.body,
  timestamp: new Date().toISOString()
});

Next Steps

Chat Completions

Start building chat features with secure authentication

Media & Vision

Add vision capabilities to your authenticated app

Tool Calling

Implement function calling with proper authentication

Event System

Handle authentication events in your application

Get Started

SDK Features

Advanced SDK

REST API Integration

Models

Security Architecture

Why Token Provider?

Authentication Flow

Backend Implementation

Basic Token Provider Endpoint

Frontend Integration

Basic SDK Configuration

User Authentication Integration

Managing User Sessions

Advanced Authentication

Custom Token Storage

Token Refresh Handling

Manual Token Management

CORS Configuration

Troubleshooting

Common Issues

Debug Mode

Next Steps

Chat Completions

Media & Vision

Tool Calling

Event System

​Security Architecture

​Why Token Provider?

​Authentication Flow

​Backend Implementation

​Basic Token Provider Endpoint

​Frontend Integration

​Basic SDK Configuration

​User Authentication Integration

​Managing User Sessions

​Advanced Authentication

​Custom Token Storage

​Token Refresh Handling

​Manual Token Management

​CORS Configuration

​Troubleshooting

​Common Issues

​Debug Mode

​Next Steps

Chat Completions

Media & Vision

Tool Calling

Event System

Security Architecture

Why Token Provider?

Authentication Flow

Backend Implementation

Basic Token Provider Endpoint

Frontend Integration

Basic SDK Configuration

User Authentication Integration

Managing User Sessions

Advanced Authentication

Custom Token Storage

Token Refresh Handling

Manual Token Management

CORS Configuration

Troubleshooting

Common Issues

Debug Mode

Next Steps