​
Authentication

Nebula API uses API keys as the primary authentication method. API keys provide granular permissions and are scoped to specific clusters.
Recommended: load keys from environment variables; do not commit secrets. Always use HTTPS and send credentials via the Authorization header.

​
TL;DR

  • Authorization header format: Authorization: ApiKey neb_xxx (never in query params)
  • Quick health check expects HTTP 200
  • Initialize SDKs by reading the API key from an environment variable
# Quick health check (replace YOUR_API_KEY)
curl -s -H "Authorization: ApiKey YOUR_API_KEY" \
  https://api.nebulacloud.app/v1/health

​
API Keys

API keys are the primary authentication method for the Nebula API. They provide granular permissions and are scoped to specific clusters.

​
Creating API Keys

API keys can be created through the Nebula dashboard.

​
Via Dashboard

  1. Log in to your Nebula dashboard
  2. Navigate to API Keys section
  3. Click Create New API Key
  4. Configure permissions for specific clusters
  5. Copy the generated API key (it’s only shown once)
API keys are shown only once. Store them securely and never commit them to source control.

​
Permission Levels

API keys support different permission levels:
PermissionDescription
readCan view and download files
writeCan upload, create folders, delete, move, and rename files (includes read permissions)
adminFull access to the cluster
noneNo access

​
Using API Keys

# See Quick Start -> Initialize Client for full example

​
Retries and rate limits

Use capped exponential backoff with jitter for transient errors (e.g., 429/5xx). Avoid retrying non-idempotent writes unless the operation supports idempotency. 
import os, random, time
from typing import Callable, TypeVar

T = TypeVar("T")

def retry_with_jitter(fn: Callable[[], T], retries: int = 3, base: float = 0.3, factor: float = 2.0, cap: float = 5.0) -> T:
    for i in range(retries):
        try:
            return fn()
        except Exception as e:
            if i == retries - 1:
                raise
            exp = min(cap, base * (factor ** i))
            time.sleep(random.random() * exp)  # full jitter

​
Security Best Practices

​
API Key Security

  1. Keep API keys secret: Never commit API keys to version control
  2. Use environment variables: Store API keys in environment variables
  3. Limit permissions: Use the minimum required permissions for each API key
  4. Monitor usage: Regularly check API key usage in the dashboard

​
Environment Variables

# .env file
NEBULA_API_KEY=neb_abcdef123456789

# In your code
import os
from dotenv import load_dotenv
from nebula_client import NebulaClient

load_dotenv()
client = NebulaClient(api_key=os.getenv("NEBULA_API_KEY"))

​
Quick Test

Verify your key quickly: 
curl -s -H "Authorization: ApiKey YOUR_API_KEY" \
  https://api.nebulacloud.app/v1/health

​
Common errors

  • 401 Unauthorized: Missing/invalid Authorization header. Do not retry without fixing credentials.
  • 403 Forbidden: Authenticated but insufficient permissions or wrong cluster scope. Do not retry without changing permissions/scope.
  • 429 Too Many Requests: Back off with jitter and retry after delay; respect any rate-limit headers if present.

​
Rotation and revocation

  • Prefer environment variables or a secrets manager; never hardcode keys.
  • Rotate keys periodically and immediately after suspected exposure.
  • Revoke unused keys in the dashboard and monitor usage for anomalies.

​
Next Steps