Skip to content

Migration Guide

This guide helps you migrate to the new authentication system and API structure.

Overview

The Fermi platform uses:

  1. Token Exchange: Convert API keys to short-lived tokens
  2. Feature-Based APIs: APIs organized by features (Analytics, Brain, Data Connectors)
  3. Service Actors: Non-human actors for automated systems

Migration Steps

Step 1: Create API Keys

Create new API keys with the required scopes:

curl -X POST https://api.fermi.dev/public/v1/identity/api-keys \
  -H "Authorization: Bearer <your-user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Migration API Key",
    "scopes": ["provision:service:create", "provision:token:exchange"]
  }'

Step 2: Create Service Actors

Create service actors for automated systems:

curl -X POST https://api.fermi.dev/public/v1/identity/service-actors \
  -H "Authorization: Bearer fmk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Service Actor",
    "organisationId": "your-org-id",
    "capabilities": ["analytics:query"]
  }'

Step 3: Exchange for Tokens

Exchange API keys for service actor tokens:

curl -X POST https://api.fermi.dev/public/v1/identity/auth/token/exchange \
  -H "Authorization: Bearer fmk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceActorId": "service-actor-id"
  }'

Step 4: Use Tokens for API Calls

Use the token to access data:

curl -X POST https://api.fermi.dev/agents-service/api/v1/agentcore/chat \
  -H "Authorization: Bearer <service-actor-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were last month sales?",
    "session_id": "my-chat-session-123"
  }'

Migration Checklist

  • [ ] Created new API keys with required scopes
  • [ ] Created service actors (if using automation)
  • [ ] Updated endpoint URLs to feature-based structure
  • [ ] Tested token exchange (if applicable)
  • [ ] Tested all API calls
  • [ ] Deployed to production
  • [ ] Monitored for issues

Common Issues and Solutions

Missing Scope Error

{
  "error": "Forbidden",
  "message": "Missing required scope: analytics:query"
}

Solution: Create a new API key with the required scope, or rotate your existing key to add the scope.

Invalid Endpoint

{
  "error": "Not Found",
  "message": "Endpoint not found"
}

Solution: Update endpoint URL to use feature-based structure (e.g., /public/v1/analytics/...).

Support and Resources

Next Steps