Authentication¶

This page describes the authentication mechanisms used in the Bluefly LLM ecosystem API.

Authentication Methods¶

The Bluefly LLM ecosystem supports several authentication methods:

API Keys: For server-to-server authentication
JWT Tokens: For user-based authentication
OAuth 2.0: For third-party integrations

API Key Authentication¶

API keys are used for server-to-server authentication and provide full access to the API.

Obtaining an API Key¶

API keys can be obtained through the Bluefly dashboard or by contacting the Bluefly team.

Using API Keys¶

Include the API key in the Authorization header of your requests:

GET /api/v1/models HTTP/1.1
Host: api.bluefly.io
Authorization: Bearer YOUR_API_KEY

API Key Security¶

To keep your API key secure:

Store the key securely in environment variables or secrets managers
Rotate keys regularly
Use different keys for development and production
Set appropriate permissions for each key

JWT Authentication¶

JSON Web Tokens (JWT) are used for user-based authentication.

Obtaining a JWT Token¶

Authenticate the user with username and password:

POST /api/v1/auth/login HTTP/1.1
Host: api.bluefly.io
Content-Type: application/json

{
  "username": "[email protected]",
  "password": "your_password"
}

Receive a JWT token in the response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "abc123...",
  "expiresIn": 3600
}

Using JWT Tokens¶

Include the JWT token in the Authorization header of your requests:

GET /api/v1/user/profile HTTP/1.1
Host: api.bluefly.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Refreshing JWT Tokens¶

JWT tokens expire after a specified time. To refresh a token:

POST /api/v1/auth/refresh HTTP/1.1
Host: api.bluefly.io
Content-Type: application/json

{
  "refreshToken": "abc123..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "def456...",
  "expiresIn": 3600
}

OAuth 2.0 Authentication¶

OAuth 2.0 is used for third-party integrations.

Authorization Code Flow¶

Redirect the user to the Bluefly authorization endpoint:

https://api.bluefly.io/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=models.read,models.generate

The user authorizes your application and is redirected back to your redirect URI with an authorization code:

https://your-app.com/callback?code=AUTHORIZATION_CODE

Exchange the authorization code for an access token:

POST /oauth/token HTTP/1.1
Host: api.bluefly.io
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://your-app.com/callback

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "ghi789...",
  "scope": "models.read models.generate"
}

Client Credentials Flow¶

For server-to-server OAuth 2.0 authentication:

POST /oauth/token HTTP/1.1
Host: api.bluefly.io
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=models.read,models.generate

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "models.read models.generate"
}

Authentication Best Practices¶

Use HTTPS: Always use HTTPS to encrypt communication
Secure Storage: Store credentials securely (environment variables, secrets managers)
Principle of Least Privilege: Request only the permissions your application needs
Token Validation: Validate tokens on the client side before using them
Refresh Handling: Implement proper token refresh logic
Error Handling: Handle authentication errors gracefully
Logging: Log authentication events for auditing
Rate Limiting: Implement rate limiting for authentication requests

Troubleshooting Authentication Issues¶

Common authentication issues and solutions:

Invalid API Key¶

Error:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}

Solution: Verify that the API key is correct and properly formatted.

Expired JWT Token¶

Error:

{
  "error": {
    "code": "token_expired",
    "message": "The access token has expired"
  }
}

Solution: Refresh the token using the refresh token.

Invalid OAuth Scope¶

Error:

{
  "error": {
    "code": "insufficient_scope",
    "message": "The request requires higher privileges than provided by the access token"
  }
}

Solution: Request the appropriate scopes during the OAuth flow.