Authentication & Authorization

API version: v1 Estimated reading time: 10 minutes Audience: Integrators and backend developers

Booga Enterprise supports multiple authentication mechanisms. For programmatic integrations, API keys are the primary method. This guide explains how to obtain a key, authenticate requests, understand scope-based authorization, and follow security best practices.

Authentication Methods

Method	Use Case	How It Works
API Key	Server-to-server integrations, automated scripts, external applications	Pass a key in the request header; the platform resolves the tenant and enforces scopes
Session (Cookie)	Browser-based access via the web UI	Handled automatically by the frontend; not used for API integrations
JWT (Azure AD B2C)	Interactive API Explorer, Swagger UI, OpenAPI schema access	Bearer token from Azure AD B2C identity provider

For most integration scenarios, you will use API keys.

API Keys

Obtaining an API Key

API keys are created in the API Management plugin within the Booga Enterprise dashboard. You need the API_MANAGEMENT_WRITE permission on your account.

1. Navigate to API Management → API Keys tab
2. Click Create API Key
3. Enter a descriptive name (e.g., "Reporting Dashboard" or "CI/CD Pipeline")
4. Select the scopes the key needs (see Scopes below)
5. Configure rate limits and optional IP restrictions
6. Click Create

The full API key is displayed exactly once after creation. Copy it immediately and store it in a secure credential store (e.g., environment variable, vault, or secrets manager). The platform stores only a PBKDF2-hashed version and cannot recover the original key.

Important: API key management is available only to corporate tenants. Developer (B2C individual) tenants do not have access to API key creation.

Passing the API Key

Include your API key in every request using one of these methods:

Option 1 — Authorization header (recommended):

GET /api/files/ HTTP/1.1
Host: api.boogaenterprise.com
Authorization: Bearer bge_a1b2c3d4e5f6g7h8i9j0...

Option 2 — X-API-Key header:

GET /api/files/ HTTP/1.1
Host: api.boogaenterprise.com
X-API-Key: bge_a1b2c3d4e5f6g7h8i9j0...

Both methods are functionally equivalent. When using Authorization: Bearer, the middleware distinguishes API keys from JWTs by format — JWTs contain dots (.) while API keys do not.

Key Lifecycle

Status	Description
Active	Key is valid and accepting requests
Expired	Key has passed its expiration date; requests are rejected with 401
Revoked	Key has been permanently disabled by an administrator; requests are rejected with 401

The platform sends expiration warnings at 7 days and 1 day before a key expires, giving you time to rotate credentials.

Scopes

Scopes control which endpoints and operations an API key can access. They map directly to the platform's role-based access control (RBAC) permissions.

Available Scopes

Scope	Access Granted
FILES_READ	List and download files
FILES_WRITE	Upload and update files
FILES_DELETE	Delete files
FILES_UPLOAD	Upload files (specifically)
FILES_DOWNLOAD	Download files (specifically)
FILES_EMBED	Create file embeddings for knowledge base
FILES_FOLDER_MANAGE	Create, rename, and delete folders
CHAT_READ	List chat sessions and messages
CHAT_WRITE	Create sessions and send messages
CHAT_DELETE	Delete chat sessions
AGENTS_READ	List agents and configurations
AGENTS_WRITE	Create and update agents
AGENTS_EXECUTE	Trigger agent execution
AGENTS_MANAGE	Full agent management including templates
KNOWLEDGE_READ	Search and browse knowledge base
KNOWLEDGE_WRITE	Add and update knowledge base content
REPORTS_READ	Retrieve and list reports
REPORTS_WRITE	Generate and schedule reports
ANALYTICS_READ	Query analytics dashboards and metrics
ANALYTICS_WRITE	Create and modify analytics configurations
ORGANIZATIONS_READ	List organisations and members
ORGANIZATIONS_WRITE	Manage organisation settings and membership
INTEGRATIONS_READ	View integration connections and status
INTEGRATIONS_WRITE	Configure connectors and sync pipelines
SCHEDULER_READ	List scheduled tasks
SCHEDULER_WRITE	Create and update scheduled tasks
SCHEDULER_EXECUTE	Trigger scheduled tasks manually
SCHEDULER_MANAGE	Full scheduler management
BOTS_CREATE	Create embeddable chat bots
BOTS_MANAGE	Full bot lifecycle management
COLLECTIONS_ASSIGN	Assign resources to collections
COLLECTIONS_MANAGE	Create and manage collections

Scope Enforcement

When a request arrives with an API key, the middleware:

1. Resolves the endpoint path and HTTP method to the required scope(s) using an internal mapping
2. Checks that the key's granted scopes include all required scopes
3. Returns 403 Forbidden if any required scope is missing

The response for a scope violation:

{
  "detail": "API key does not have the required scope for this endpoint.",
  "code": "insufficient_scope",
  "required_scopes": ["FILES_WRITE"],
  "key_scopes": ["FILES_READ"]
}

Scope Assignment Rules

• You can only assign scopes that match your own RBAC permissions — you cannot create a key with more access than your account has
• Admin-level scopes (ADMIN_ACCESS, SUPERUSER_ACCESS, API_MANAGEMENT_READ, API_MANAGEMENT_WRITE) cannot be assigned to API keys
• The available scopes for your account are visible in the API Management UI when creating a key, or via GET /api/api-management/api-keys/available_scopes/

IP Restrictions

API keys support optional IP-based access control:

• Allowed IPs — if set, requests are accepted only from these addresses
• Blocked IPs — requests from these addresses are always rejected

Both fields accept individual IPv4/IPv6 addresses. Configure these restrictions when creating or editing a key in the API Management console.

When a request is rejected due to IP restrictions, the API returns 403 Forbidden with a message indicating the IP is not permitted.

Security Policy

Beyond scope enforcement, a security policy protects sensitive endpoints from API key access entirely. Approximately 469 internal endpoints (admin operations, tenant management, authentication flows, and similar) are blocked from all API key access regardless of scopes. These endpoints are accessible only via authenticated browser sessions.

If you attempt to access a protected endpoint with an API key, the API returns:

{
  "detail": "This endpoint is not accessible via API keys.",
  "code": "endpoint_blocked"
}

Tenant Isolation

API keys are bound to the tenant that created them. Every request authenticated with an API key operates within that tenant's data boundary:

• Queries return only data belonging to the key's tenant
• Resource creation assigns ownership to the key's tenant
• Cross-tenant access is not possible via API keys
• The middleware validates that any tenant or stack identifiers in the request path or body match the key's tenant

Best Practices

• Use a dedicated key per integration — if one key is compromised, you can revoke it without disrupting other integrations
• Grant the minimum scopes necessary — a reporting client needs only REPORTS_READ and ANALYTICS_READ, not write scopes
• Store keys securely — use environment variables, a secrets manager, or a CI/CD vault; never embed keys in client-side code or commit them to source control
• Rotate keys periodically — create a new key, update your integration, verify it works, then revoke the old key
• Enable IP restrictions for production — restrict production keys to your server's known IP addresses
• Set appropriate rate limits — start conservative (default: 60/min, 3,600/hour) and adjust based on legitimate traffic patterns
• Monitor usage analytics — review the API Management Analytics tab weekly to catch unusual patterns, rising error rates, or unauthorised access attempts
• Handle 401 and 403 gracefully — implement retry logic for transient failures and clear error reporting for permanent authorization issues

Troubleshooting

401 Unauthorized

The API key is missing, malformed, expired, or revoked. Verify:

• The key is included in the Authorization or X-API-Key header
• The key status is Active in the API Management console
• The key has not passed its expiration date

403 Forbidden

The key is valid but lacks permission. Check:

• The key's scopes include the scope required by the endpoint you are calling
• The endpoint is not on the security policy blocklist (admin/internal endpoints)
• IP restrictions are not blocking your request source

429 Too Many Requests

Your key has exceeded its rate limit. The response headers indicate your limits and remaining quota. Implement exponential backoff and consider increasing the key's rate limits if the traffic is legitimate.

Related Topics

• Using the API — base URL, pagination, errors, and conventions
• Architecture Overview — how authentication fits into the request flow
• Integration Getting Started — build your first integration
• API Management — User Guide — manage keys and analytics from the dashboard
• API Reference — interactive OpenAPI documentation for every endpoint

Related Topics

• Using the API
• Architecture Overview
• API Management

---

⏱️ Read time: 10 minutes | 📊 Difficulty: intermediate