Projects API

The Projects API allows you to manage Firebase projects connected to FireBackup. You can list, create, update, and delete project connections, as well as manage collections.

Endpoints Overview

Method	Endpoint	Description
GET	/projects	List all projects
POST	/projects	Create (connect) a project
GET	/projects/:id	Get project details
PUT	/projects/:id	Update project
DELETE	/projects/:id	Delete (disconnect) project
GET	/projects/:id/collections	List collections
POST	/projects/:id/collections/sync	Sync collections

List Projects

Retrieve all projects in the current organization.

GET /api/v1/projects
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
status	string	-	Filter by status: connected, disconnected, error
search	string	-	Search by name or Firebase project ID

Response:

{
  "success": true,
  "data": [
    {
      "id": "proj_abc123",
      "name": "Production App",
      "firebaseProjectId": "my-firebase-prod",
      "status": "connected",
      "credentialType": "oauth",
      "collectionsCount": 12,
      "lastBackupAt": "2024-01-15T10:00:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

Get Project

Retrieve details of a specific project.

GET /api/v1/projects/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Path Parameters:

Parameter	Type	Description
id	string	Project ID

Response:

{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "Production App",
    "firebaseProjectId": "my-firebase-prod",
    "status": "connected",
    "credentialType": "oauth",
    "tokenStatus": {
      "valid": true,
      "expiresAt": "2024-01-15T11:00:00Z",
      "scopes": [
        "https://www.googleapis.com/auth/datastore",
        "https://www.googleapis.com/auth/firebase"
      ]
    },
    "settings": {
      "defaultStorageId": "storage_xyz789",
      "compression": "brotli",
      "encryption": true,
      "includeAuth": false
    },
    "collections": [
      { "name": "users", "documentCount": 15000 },
      { "name": "orders", "documentCount": 45000 }
    ],
    "statistics": {
      "totalBackups": 42,
      "totalSize": 1250000000,
      "lastBackupAt": "2024-01-15T10:00:00Z",
      "lastBackupStatus": "completed"
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Create Project

Connect a new Firebase project to FireBackup.

POST /api/v1/projects
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "firebaseProjectId": "my-firebase-prod",
  "name": "Production App",
  "credentials": {
    "type": "oauth",
    "accessToken": "ya29.xxx...",
    "refreshToken": "1//xxx..."
  },
  "settings": {
    "defaultStorageId": "storage_xyz789",
    "compression": "brotli",
    "encryption": true,
    "includeAuth": false
  }
}

Request Body:

Field	Type	Required	Description
firebaseProjectId	string	Yes	Firebase project ID
name	string	No	Display name (defaults to Firebase project name)
credentials.type	string	Yes	oauth or service_account
credentials.accessToken	string	Conditional	OAuth access token
credentials.refreshToken	string	Conditional	OAuth refresh token
credentials.serviceAccountJson	object	Conditional	Service account JSON
settings.defaultStorageId	string	No	Default storage destination
settings.compression	string	No	brotli or gzip
settings.encryption	boolean	No	Enable encryption (default: true)
settings.includeAuth	boolean	No	Include Auth users in backups

Response:

{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "Production App",
    "firebaseProjectId": "my-firebase-prod",
    "status": "connected",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Update Project

Update project settings or credentials.

PUT /api/v1/projects/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "name": "Production App (Updated)",
  "settings": {
    "defaultStorageId": "storage_new456",
    "compression": "gzip",
    "encryption": true,
    "includeAuth": true
  }
}

Request Body:

Field	Type	Description
name	string	Display name
credentials	object	New credentials (triggers re-verification)
settings	object	Project settings

Response:

{
  "success": true,
  "data": {
    "id": "proj_abc123",
    "name": "Production App (Updated)",
    "status": "connected",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Delete Project

Disconnect a project from FireBackup.

DELETE /api/v1/projects/:id
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Query Parameters:

Parameter	Type	Default	Description
deleteBackups	boolean	false	Also delete all backups

Response:

{
  "success": true,
  "message": "Project disconnected successfully"
}

Backup Retention

By default, backups are retained when disconnecting a project. Use deleteBackups=true to remove them.

List Collections

Get all Firestore collections for a project.

GET /api/v1/projects/:id/collections
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "collections": [
      {
        "name": "users",
        "documentCount": 15000,
        "estimatedSize": 45000000,
        "subcollections": ["settings", "notifications"]
      },
      {
        "name": "orders",
        "documentCount": 45000,
        "estimatedSize": 120000000,
        "subcollections": ["items", "payments"]
      }
    ],
    "lastSyncedAt": "2024-01-15T10:00:00Z"
  }
}

Sync Collections

Refresh the collection list from Firestore.

POST /api/v1/projects/:id/collections/sync
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "collections": [
      { "name": "users", "documentCount": 15500 },
      { "name": "orders", "documentCount": 46000 },
      { "name": "products", "documentCount": 1200 }
    ],
    "added": ["products"],
    "removed": [],
    "syncedAt": "2024-01-15T11:00:00Z"
  }
}

Verify IAM Permissions

Check if credentials have required IAM permissions.

POST /api/v1/projects/:id/verify-iam
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "permissions": {
      "datastore.viewer": true,
      "datastore.importExportAdmin": true,
      "firebase.viewer": true,
      "identitytoolkit.viewer": false
    },
    "warnings": [
      "Missing identitytoolkit.viewer: Firebase Auth backup will not be available"
    ]
  }
}

Refresh OAuth Token

Manually refresh the OAuth token for a project.

POST /api/v1/projects/:id/refresh-token
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "tokenStatus": {
      "valid": true,
      "expiresAt": "2024-01-15T12:00:00Z",
      "refreshedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Project Object

Field	Type	Description
id	string	Unique project ID
name	string	Display name
firebaseProjectId	string	Firebase project identifier
status	string	connected, disconnected, error
credentialType	string	oauth or service_account
tokenStatus	object	OAuth token status (if applicable)
settings	object	Project settings
collections	array	List of collections
statistics	object	Backup statistics
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp

Error Responses

Project Not Found

{
  "success": false,
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project with ID 'proj_xxx' not found"
  }
}

Invalid Credentials

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Failed to connect to Firebase project",
    "details": {
      "reason": "Token expired or revoked"
    }
  }
}

IAM Permission Denied

{
  "success": false,
  "error": {
    "code": "IAM_PERMISSION_DENIED",
    "message": "Missing required IAM permissions",
    "details": {
      "missing": ["roles/datastore.importExportAdmin"]
    }
  }
}

Related

• Backups API - Create backups for projects
• Schedules API - Schedule automated backups
• Managing Projects - User guide