Authentication

FireBackup uses OAuth 2.0 with Google for authentication, providing secure access to your Firebase projects through Google's identity platform.

Authentication Methods

FireBackup supports two authentication methods:

Method	Use Case	Token Lifetime
OAuth Access Token	Interactive applications	1 hour
Service Account API Key	Server-to-server	Long-lived

OAuth 2.0 Flow

Step 1: Initiate OAuth

Redirect users to the Google OAuth endpoint:

GET /api/v1/auth/google

Query Parameters:

Parameter	Type	Required	Description
redirect_uri	string	No	Custom callback URL

Response:

Redirects to Google OAuth consent screen.

Step 2: Handle Callback

After user authorization, Google redirects to:

/api/v1/auth/google/callback?code=AUTH_CODE

FireBackup exchanges the code for tokens and redirects to your application with the session established.

Step 3: Get Access Token

For API clients, exchange the authorization code:

POST /api/v1/auth/token
Content-Type: application/json

{
  "code": "AUTH_CODE_FROM_CALLBACK",
  "grant_type": "authorization_code"
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_abc123...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

Using Access Tokens

Include the access token in all API requests:

curl -X GET https://api.firebackup.io/api/v1/projects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Organization-Id: YOUR_ORG_ID"

Required Headers

Header	Description
Authorization	Bearer token: Bearer <access_token>
X-Organization-Id	Organization UUID for multi-tenant requests
Content-Type	application/json for POST/PUT/PATCH requests

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to obtain new access tokens:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "refresh_abc123..."
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_new456...",
    "expiresIn": 3600
  }
}

Auto-Refresh

When using our SDKs, token refresh is handled automatically. See SDKs & Packages for details.

Get Current User

Retrieve information about the authenticated user:

GET /api/v1/auth/me
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "success": true,
  "data": {
    "id": "user_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "picture": "https://lh3.googleusercontent.com/...",
    "organizations": [
      {
        "id": "org_xyz789",
        "name": "My Company",
        "role": "owner"
      }
    ],
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Logout

Invalidate the current session:

POST /api/v1/auth/logout
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

Service Account Authentication

For server-to-server communication, use service account API keys:

Creating a Service Account

1. Go to Settings > Organization in the dashboard
2. Navigate to Service Accounts
3. Click Create Service Account
4. Configure permissions
5. Copy the generated API key

Using Service Account Keys

curl -X GET https://api.firebackup.io/api/v1/backups \
  -H "Authorization: Bearer SERVICE_ACCOUNT_API_KEY" \
  -H "X-Organization-Id: YOUR_ORG_ID"

Service Account Permissions

Scope	Description
backups:read	List and view backups
backups:write	Create, restore, and delete backups
schedules:read	View schedules
schedules:write	Create, modify, and delete schedules
projects:read	View connected projects
projects:write	Connect and manage projects
storage:read	View storage destinations
storage:write	Configure storage destinations
organization:read	View organization details
organization:write	Manage organization settings

JWT Token Structure

FireBackup JWTs contain the following claims:

{
  "sub": "user_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "organizations": ["org_xyz789"],
  "iat": 1705330800,
  "exp": 1705334400
}

Claim	Description
sub	User ID
email	User email
name	User display name
organizations	Array of organization IDs
iat	Issued at timestamp
exp	Expiration timestamp

Google OAuth Scopes

FireBackup requests the following Google OAuth scopes:

Scope	Purpose
openid	OpenID Connect identity
email	User email address
profile	User name and picture
https://www.googleapis.com/auth/firebase	Firebase project access
https://www.googleapis.com/auth/cloud-platform	Google Cloud access
https://www.googleapis.com/auth/datastore	Firestore access

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Common causes:

• Token expired
• Token revoked
• Invalid token format

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

Common causes:

• User lacks required role
• Service account missing scope
• Organization access denied

Security Best Practices

Token Storage

• Never store tokens in version control
• Use environment variables for service account keys
• Store tokens securely (encrypted at rest)
• Use HTTP-only cookies for browser sessions

Token Rotation

• Refresh tokens before expiration
• Rotate service account keys periodically
• Revoke compromised tokens immediately

Network Security

• Always use HTTPS
• Validate SSL certificates
• Use secure headers (HSTS, CSP)

SDK Examples

JavaScript/TypeScript

import { FireBackupClient } from '@firebackup/sdk';

// OAuth token
const client = new FireBackupClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  organizationId: 'YOUR_ORG_ID'
});

// Service account
const client = new FireBackupClient({
  apiKey: 'SERVICE_ACCOUNT_KEY',
  organizationId: 'YOUR_ORG_ID'
});

// Auto-refresh enabled
const client = new FireBackupClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  refreshToken: 'YOUR_REFRESH_TOKEN',
  organizationId: 'YOUR_ORG_ID',
  autoRefresh: true
});

Python

from firebackup import FireBackupClient

# OAuth token
client = FireBackupClient(
    access_token="YOUR_ACCESS_TOKEN",
    organization_id="YOUR_ORG_ID"
)

# Service account
client = FireBackupClient(
    api_key="SERVICE_ACCOUNT_KEY",
    organization_id="YOUR_ORG_ID"
)

Related

• Error Codes - Complete error reference
• Rate Limiting - API rate limits
• SDKs & Packages - Official SDK documentation