Skip to content

Getting Started

Quick start guide for integrating with Fermi Platform APIs.

Authentication

API keys are used to create and manage organizations and service actors. For data access, use service actor tokens.

Authentication Methods:

  • API Keys: Create organizations and service actors
  • Service Actor Tokens: Access data from services (Brain, Analytics, Connectors, etc.)

Quick Start Flow

flowchart LR
    A[Get API Key] --> B[Create Organization]
    B --> C[Create Service Actor]
    C --> D[Exchange for Token]
    D --> E[Access Platform APIs]

1. Get API Key

Required scopes for basic integration:

  • provision:org:create - Create organizations
  • provision:service:create - Create service actors
  • provision:token:exchange - Exchange for tokens

API Key

2. Create Organization

Use your API key to create an organization where your service actors will belong:

curl -X POST https://api.fermi.dev/public/v1/identity/organisations/api-key \
  -H "Authorization: Bearer fmk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Service Organization",
    "domain": "https://my-service.example.com"
  }'

Response: 

{
  "organisation": {
    "id": "507f1f77bcf86cd799439011",
    "name": "My Service Organization",
    "domain": "example.com"
  }
}

domain must be a URL. The API stores the root domain. Save organisation.id for creating service actors.

Organization Onboarding

3. Create Service Actor

Use the organization ID from step 2 to create a service actor:

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 '{
    "organisationId": "507f1f77bcf86cd799439011",
    "name": "My Analytics Service Actor",
    "capabilities": ["analytics:query", "brain:read", "brain:write"],
    "status": "active"
  }'

Response: 

{
  "success": true,
  "message": "Service actor created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439012",
    "name": "My Analytics Service Actor",
    "capabilities": ["analytics:query", "brain:read", "brain:write"],
    "status": "active"
  }
}

Save data.id (service actor ID) for token exchange. Valid brain capabilities are brain:read and brain:write. There is no brain:access scope.

Service Actors

4. Exchange for Service Actor Token

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": "507f1f77bcf86cd799439012"
  }'

The live path is /auth/token/exchange (singular token).

Response: 

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900,
  "expiresAt": 1710000900000,
  "actorType": "service",
  "organisationId": "507f1f77bcf86cd799439011",
  "scopes": ["analytics:query", "brain:read", "brain:write"]
}

Use token as Authorization: Bearer <token> on Chat, Brain, and connector APIs.

Token Exchange

Response Codes

  • 200 - Success
  • 201 - Created
  • 401 - Invalid API key
  • 403 - Missing scope or forbidden
  • 404 - Resource not found
  • 422 - Validation error
  • 429 - Rate limit exceeded

Confirm the API key with GET https://api.fermi.dev/public/v1/identity/service-actors (not GET /public/v1/analytics/status).

Common Use Cases

Follow the product journey after you have a service actor token:

  1. Onboarding — POST /public/v1/analytics/chat with "action": "onboarding" and "step": 1
  2. Connectors — connectors:read, connectors:write, connectors:sync
  3. Brain — brain:read / brain:write — POST /public/v1/analytics/perform/action
  4. Validation — list and review findings after connectors
  5. Chat — Ask Fermi on /agents-service/api/v1/agentcore/...
  6. Tasks — Fermi app user session on app.fermi.dev (not a service-actor token)
  7. Forms — public slug + submit

Next Steps