Backup EnginebackupEngine
Docs/API Reference/Authentication

API Authentication

Authenticate with the BackupEngine API using JWT tokens, device keys, and MFA verification.

Authentication Methods

BackupEngine uses Supabase Auth as its authentication provider. There are two primary authentication methods depending on whether you are building a user-facing integration or an automated agent.

  • •User authentication: Email/password or OAuth (Google, Microsoft, Apple) with mandatory MFA. Returns a JWT access token and refresh token.
  • •Device key authentication: A long-lived key pair registered to a specific device. Used by the desktop agent and automated scripts. Does not require MFA after initial device registration.

User Login Flow

The user login flow requires email, password, and a TOTP MFA code. All API calls must include the resulting JWT access token in the Authorization header.

Login request
POST /auth/v1/token?grant_type=password
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-secure-password"
}

// Response (requires MFA verification):
{
  "mfa_required": true,
  "mfa_token": "mfa_temp_abc123",
  "factors": [
    { "id": "factor_01", "type": "totp", "friendly_name": "Authenticator App" }
  ]
}
MFA verification
POST /auth/v1/factors/factor_01/verify
Content-Type: application/json
Authorization: Bearer mfa_temp_abc123

{
  "code": "123456"
}

// Response (authenticated):
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "v1.refresh.abc123...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "role": "owner"
  }
}

Using Access Tokens

Include the access token in the Authorization header of all API requests. Access tokens expire after 1 hour and must be refreshed using the refresh token.

Authenticated API request
GET /rest/v1/devices
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

// Response:
{
  "devices": [
    {
      "id": "dev_abc123",
      "name": "Work Laptop",
      "os": "Windows 11",
      "agent_version": "2.4.1",
      "last_backup": "2025-12-15T02:15:00Z",
      "status": "healthy"
    }
  ]
}
Refreshing an expired token
POST /auth/v1/token?grant_type=refresh_token
Content-Type: application/json

{
  "refresh_token": "v1.refresh.abc123..."
}

// Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...(new token)",
  "refresh_token": "v1.refresh.xyz789...(new refresh token)",
  "expires_in": 3600
}

⚠ Warning

Always store refresh tokens securely. A compromised refresh token allows an attacker to generate new access tokens. On mobile and desktop clients, store tokens in the platform's secure keychain/credential store.

Device Key Authentication

Device keys are used by the desktop agent and automated scripts. They are registered once with MFA verification and then used for ongoing authentication without MFA prompts.

Device key authentication
POST /functions/v1/auth/device
Content-Type: application/json

{
  "device_key": "dk_live_abc123...",
  "device_id": "dev_abc123",
  "signature": "sha256_hmac_of_timestamp_and_device_id"
}

// Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 3600,
  "device": {
    "id": "dev_abc123",
    "name": "Production Server",
    "permissions": ["backup", "restore", "status"]
  }
}

ℹ Note

Device keys can be scoped to specific permissions (backup, restore, status, config). For automated backup scripts, create a key with only the backup and status permissions to follow the principle of least privilege.
JSON OutputBackup API