​
Authentication

MangroveAI supports multiple authentication methods to accommodate different use cases.

​
Authentication Methods

MethodBest ForFlow
Firebase OAuthWeb apps, mobile appsFirebase SSO -> Exchange for JWT -> Use JWT
API KeysScripts, server-to-server, agentsGenerate key via portal -> Use in Authorization header
GCP IAM TokensCloud infrastructuregcloud auth print-identity-token -> Use in header

​
Step 1: Client-Side Firebase Authentication

import { initializeApp } from 'firebase/app';
import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "mangroveai-dev.firebaseapp.com",
  projectId: "mangroveai-dev"
};

const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

const provider = new GoogleAuthProvider();
const result = await signInWithPopup(auth, provider);
const firebaseToken = await result.user.getIdToken();

​
Step 2: Exchange for MangroveAI JWT

curl -X POST http://localhost:5001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "firebase_token": "YOUR_FIREBASE_TOKEN"
  }'
Response: 
{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "user": {
    "id": "uuid",
    "name": "John Doe",
    "email": "john@example.com",
    "org_id": "uuid"
  }
}
Token Lifetimes:
  • Access token: 1 hour
  • Refresh token: 30 days

​
Step 3: Use JWT for API Requests

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://localhost:5001/api/v1/signals

​
Generate an API Key

Requires an active JWT session first: 
curl -X POST http://localhost:5001/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server Key",
    "scopes": ["read:strategies", "write:backtests"],
    "expires_days": 365
  }'
Response: 
{
  "success": true,
  "key": "dev_a1b2c3d4e5f6...",
  "key_id": "uuid-here",
  "key_prefix": "dev_a1b2c3d4",
  "name": "Production Server Key",
  "created_at": "2025-12-01T10:00:00Z",
  "expires_at": "2026-12-01T10:00:00Z"
}
Save the key value immediately. It is only shown once and cannot be retrieved later.

​
Use the API Key

curl -H "Authorization: Bearer dev_a1b2c3d4e5f6..." \
  http://localhost:5001/api/v1/signals

​
Token Refresh

When your access token expires, use the refresh token to obtain a new one: 
curl -X POST http://localhost:5001/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

​
API Endpoints

MethodEndpointDescription
POST/api/v1/auth/loginExchange Firebase token for JWT
POST/api/v1/auth/refreshRefresh access token
GET/api/v1/auth/profileGet current user profile
PUT/api/v1/auth/profileUpdate user profile
POST/api/v1/auth/api-keysGenerate new API key
GET/api/v1/auth/api-keysList all API keys
DELETE/api/v1/auth/api-keys/{key_id}Revoke an API key
GET/api/v1/auth/is-adminCheck admin status

​
Authorization Levels

LevelRequiredAccess
Authenticated UserValid JWT or API keyOwn data only (strategies, backtests, conversations)
Management UserManagement API key or admin emailAll user data, platform administration
UnauthenticatedNoneHealth checks and Swagger docs only

​
Error Responses

401 Unauthorized — Token missing, invalid, or expired: 
{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}
403 Forbidden — Insufficient permissions: 
{
  "error": "Forbidden",
  "message": "Insufficient permissions for this operation"
}

​
Security Best Practices

  1. Never commit tokens or API keys to version control
  2. Use environment variables for API keys in production
  3. Rotate API keys regularly — generate new keys, revoke old ones
  4. Use minimal scopes — only request the permissions you need
  5. Set expiration dates on API keys
  6. Store access tokens in memory (not localStorage) for frontend apps
  7. Store refresh tokens in httpOnly secure cookies or secure storage