Authentication

The FAOS API uses API keys and OAuth 2.0 for authentication. Choose the method that best fits your use case.

API Keys

API keys are the simplest way to authenticate. They're ideal for server-to-server integrations and scripts.

Creating an API Key

1. Log in to app.faosx.ai
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Give it a descriptive name (e.g., "Production Server")
5. Set permissions and expiration
6. Copy the key immediately (you won't see it again)

Using API Keys

Include your API key in the Authorization header:

curl https://api.faosx.ai/v1/agents \
  -H "Authorization: Bearer sk_live_abc123xyz..."

Key Format

• Live keys: sk_live_... - Use in production
• Test keys: sk_test_... - Use in development/sandbox

Security Warning

Never commit API keys to version control or expose them client-side. Rotate keys immediately if compromised.

OAuth 2.0

OAuth 2.0 is recommended for user-facing applications where you act on behalf of end users.

OAuth Flow

sequenceDiagram
    participant User
    participant YourApp
    participant FAOS

    User->>YourApp: Click "Connect FAOS"
    YourApp->>FAOS: Redirect to /oauth/authorize
    FAOS->>User: Show consent screen
    User->>FAOS: Approve
    FAOS->>YourApp: Redirect with code
    YourApp->>FAOS: Exchange code for tokens
    FAOS->>YourApp: Return access_token + refresh_token
    YourApp->>FAOS: API calls with access_token

Step 1: Register Your Application

1. Go to Settings → OAuth Applications
2. Click New OAuth App
3. Fill in:
   • Application name: Your app's name
   • Redirect URI: Where we send users after auth
   • Scopes: Permissions your app needs

You'll receive:

• client_id: Your application's public identifier
• client_secret: Keep this secret!

Step 2: Authorization Request

Redirect users to the authorization endpoint:

GET https://app.faosx.ai/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=agents:read agents:write workflows:execute
  &state=random_string_for_csrf_protection

Parameters:

• response_type: Always code
• client_id: Your application's client ID
• redirect_uri: Must match registered URI
• scope: Space-separated permissions (see Scopes)
• state: Random string to prevent CSRF attacks

Step 3: Exchange Code for Token

After user approves, we redirect them back with a code:

https://yourapp.com/callback?code=AUTH_CODE&state=random_string

Exchange this code for an access token:

curl -X POST https://api.faosx.ai/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

Response:

{
  "access_token": "fao_access_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "fao_refresh_xyz789...",
  "scope": "agents:read agents:write workflows:execute"
}

Step 4: Use Access Token

Include the access token in API requests:

curl https://api.faosx.ai/v1/agents \
  -H "Authorization: Bearer fao_access_abc123..."

Step 5: Refresh Token

Access tokens expire after 1 hour. Use refresh tokens to get new ones:

curl -X POST https://api.faosx.ai/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=fao_refresh_xyz789..." \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Scopes

Scopes define what your application can access. Request only the scopes you need.

Scope	Description
agents:read	View agents and their configurations
agents:write	Create, update, and delete agents
agents:execute	Send messages and execute agent actions
workflows:read	View workflows
workflows:write	Create and update workflows
workflows:execute	Run workflows
integrations:read	View connected integrations
integrations:write	Connect and configure integrations
webhooks:read	View webhook subscriptions
webhooks:write	Create and manage webhooks
admin	Full access (use sparingly)

Scope Format

Multiple scopes are space-separated:

agents:read agents:write workflows:execute

Testing Authentication

Verify your credentials work:

curl https://api.faosx.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "data": {
    "user_id": "usr_abc123",
    "workspace_id": "ws_xyz789",
    "scopes": ["agents:read", "agents:write"],
    "tier": "business"
  }
}

Security Best Practices

API Keys

• ✅ Store in environment variables
• ✅ Use different keys for dev/staging/production
• ✅ Set restrictive permissions
• ✅ Rotate keys regularly (every 90 days)
• ❌ Never commit to Git
• ❌ Never expose client-side

OAuth Tokens

• ✅ Validate state parameter (CSRF protection)
• ✅ Store tokens securely (encrypted database)
• ✅ Refresh tokens before they expire
• ✅ Revoke tokens when users disconnect
• ❌ Never log tokens
• ❌ Never send tokens in URLs

Rate Limits

Authentication endpoints have stricter rate limits to prevent abuse:

Endpoint	Limit
/oauth/authorize	10 requests/minute
/oauth/token	20 requests/minute
/auth/me	60 requests/minute

See API Overview for general rate limits.

Errors

Common authentication errors:

Code	Message	Solution
invalid_token	The token is invalid or expired	Refresh or re-authenticate
insufficient_scope	Missing required scope	Request additional scopes
invalid_client	Client credentials invalid	Check client_id and client_secret
unauthorized	No authentication provided	Include Authorization header

Example Error Response:

{
  "error": {
    "code": "invalid_token",
    "message": "The access token expired",
    "expires_at": "2025-12-21T10:30:00Z"
  }
}

Next Steps

• Agents API - Create and manage agents
• Workflows API - Automate with workflows
• Webhooks - Real-time event notifications