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
  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:

X-API-Key: YOUR_API_KEY_HERE

Example Request

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

response = requests.get(
    "https://api.aitronos.com/v1/models",
    headers={"X-API-Key": api_key}
)
const response = await fetch('https://api.aitronos.com/v1/models', {
  headers: {
    'X-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}`
  }
});

Strict Request Validation

Authentication endpoints reject any request body containing fields that are not part of the documented schema. Sending an unknown field (for example, a typo like email_adress instead of email, or a deprecated field that is no longer accepted) will return a 422 Unprocessable Entity response with a VALIDATION_ERROR code.

Always validate your request payloads against the documented request body fields before sending. This strict validation helps catch integration bugs early and prevents accidental data leakage from clients sending fields that are silently ignored.

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,
    "details": {},
    "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,
    "details": {},
    "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,
    "details": {},
    "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