Skip to content
Last updated

Authentication

Freddy API supports two authentication methods: API keys and Bearer tokens. Both methods provide secure access to the API endpoints.

API Keys

API keys are the primary authentication method for Freddy API. They provide simple, long-lived access to your account.

Getting Your API Key

  1. Visit Freddy Hub
  2. Sign in to your account
  3. Navigate to API Keys section
  4. Generate a new API key
  5. Copy and store the key securely

Using API Keys

Include the API key in the request header:

api-key: YOUR_API_KEY_HERE

Example Request

curl https://api.aitronos.com/v1/models \
  -H "api-key: $FREDDY_API_KEY"
import requests

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"api-key": api_key}
)
const response = await fetch('https://api.aitronos.com/v1/models', {
  headers: {
    'api-key': process.env.FREDDY_API_KEY
  }
});

Bearer Tokens

Bearer tokens provide session-based authentication with automatic expiration and refresh capabilities.

Getting Bearer Tokens

Bearer tokens are obtained through the authentication endpoints:

  • Use your API key credentials to authenticate
  • Receive a JWT token in response
  • Include the token in subsequent requests

Using Bearer Tokens

Include the Bearer token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Example Request

curl https://api.aitronos.com/v1/models \
  -H "Authorization: Bearer $FREDDY_JWT_TOKEN"
import requests

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"Authorization": f"Bearer {jwt_token}"}
)
const response = await fetch('https://api.aitronos.com/v1/models', {
  headers: {
    'Authorization': `Bearer ${process.env.FREDDY_JWT_TOKEN}`
  }
});

Security Best Practices

API Key Security

  • Environment Variables: Store API keys in environment variables, never in code
  • Key Rotation: Regularly rotate your API keys for enhanced security
  • Minimal Permissions: Create separate keys for different applications/use cases
  • Secure Storage: Never commit API keys to version control

Bearer Token Security

  • Token Storage: Store tokens securely in memory or secure cookie storage
  • Automatic Refresh: Implement automatic token refresh before expiration
  • Secure Transmission: Always use HTTPS for API requests
  • Token Revocation: Implement proper logout to invalidate tokens

General Security

  • HTTPS Only: Always use HTTPS for all API requests
  • Request Validation: Validate all input parameters on both client and server
  • Rate Limiting: Implement client-side rate limiting to avoid hitting API limits
  • Error Handling: Don't expose sensitive information in error messages

Error Responses

401 Unauthorized

Missing Authentication

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Please sign in to continue.",
    "system_message": "Missing authentication header",
    "type": "authentication_error",
    "status": 401,
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Invalid API Key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Your API key is invalid. Please check your credentials.",
    "system_message": "API key validation failed",
    "type": "authentication_error",
    "status": 401,
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Expired Token

{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Your session has expired. Please sign in again.",
    "system_message": "JWT token expired",
    "type": "authentication_error",
    "status": 401,
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

403 Forbidden

Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to perform this action.",
    "system_message": "User lacks required permissions",
    "type": "authorization_error",
    "status": 403,
    "details": {
      "required_role": "admin"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Organization Access Denied

{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "You don't have access to this organization.",
    "system_message": "User not member of organization",
    "type": "authorization_error",
    "status": 403,
    "details": {
      "organization_id": "org_abc123"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Rate Limits

Authentication method may affect rate limits:

  • API keys: Standard rate limits apply
  • Bearer tokens: May have different limits based on account type

Check Rate Limiting for detailed information.

Troubleshooting

Common Authentication Issues

  1. "Invalid API key": Verify the key is correct and not expired
  2. "Missing authentication": Ensure you're including the proper header
  3. "Insufficient permissions": Check if your key has access to the endpoint
  4. "Account suspended": Contact support if your account is disabled

Getting Help

Previous page
Next page