Organizations API

The Organizations API enables management of organizations, team members, invitations, and service accounts. All resources in FireBackup are scoped to organizations for multi-tenant isolation.

Endpoints Overview

Method	Endpoint	Description
POST	/organizations	Create organization
GET	/organizations	List user's organizations
GET	/organizations/current	Get current organization
PUT	/organizations/current	Update current organization
POST	/organizations/current/delete	Delete organization
GET	/organizations/current/members	List members
PUT	/organizations/current/members/:userId	Update member role
DELETE	/organizations/current/members/:userId	Remove member
POST	/organizations/current/invites	Create invitation
GET	/organizations/current/invites	List invitations
DELETE	/organizations/current/invites/:inviteId	Cancel invitation
POST	/organizations/current/invites/:inviteId/resend	Resend invitation
GET	/organizations/current/service-account	Get service account
POST	/organizations/current/service-account	Create service account
DELETE	/organizations/current/service-account	Delete service account

Create Organization

Create a new organization.

POST /api/v1/organizations
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "My Company",
  "slug": "my-company"
}

Request Body:

Field	Type	Required	Description
name	string	Yes	Organization display name
slug	string	No	URL-friendly identifier (auto-generated if not provided)

Response:

{
  "success": true,
  "data": {
    "id": "org_abc123",
    "name": "My Company",
    "slug": "my-company",
    "ownerId": "user_xyz789",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

List Organizations

Get all organizations the current user belongs to.

GET /api/v1/organizations
Authorization: Bearer YOUR_TOKEN

Response:

{
  "success": true,
  "data": [
    {
      "id": "org_abc123",
      "name": "My Company",
      "slug": "my-company",
      "role": "owner",
      "memberCount": 5,
      "projectCount": 3,
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "org_def456",
      "name": "Client Project",
      "slug": "client-project",
      "role": "member",
      "memberCount": 12,
      "projectCount": 2,
      "createdAt": "2024-01-10T00:00:00Z"
    }
  ]
}

Get Current Organization

Get details of the current organization (specified by X-Organization-Id header).

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

Response:

{
  "success": true,
  "data": {
    "id": "org_abc123",
    "name": "My Company",
    "slug": "my-company",
    "owner": {
      "id": "user_xyz789",
      "email": "owner@example.com",
      "name": "John Doe"
    },
    "settings": {
      "timezone": "America/New_York",
      "defaultStorageId": "storage_abc123"
    },
    "statistics": {
      "memberCount": 5,
      "projectCount": 3,
      "backupCount": 150,
      "storageUsed": 15000000000
    },
    "subscription": {
      "plan": "pro",
      "status": "active",
      "billingCycle": "monthly"
    },
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

Update Organization

Update the current organization's settings.

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

{
  "name": "My Company (Updated)",
  "settings": {
    "timezone": "Europe/London",
    "defaultStorageId": "storage_new456"
  }
}

Request Body:

Field	Type	Description
name	string	Organization display name
settings.timezone	string	IANA timezone
settings.defaultStorageId	string	Default storage destination

Response:

{
  "success": true,
  "data": {
    "id": "org_abc123",
    "name": "My Company (Updated)",
    "settings": {
      "timezone": "Europe/London",
      "defaultStorageId": "storage_new456"
    },
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Delete Organization

Delete the current organization.

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

{
  "force": false,
  "confirmName": "My Company"
}

Request Body:

Field	Type	Required	Description
force	boolean	No	Force delete (permanent) or soft delete
confirmName	string	Yes	Organization name for confirmation

Response:

{
  "success": true,
  "data": {
    "id": "org_abc123",
    "deleted": true,
    "deletionType": "soft",
    "recoveryDeadline": "2024-02-15T11:00:00Z"
  }
}

Force Delete

Force delete permanently removes all organization data including projects, backups, and member associations. This action cannot be undone.

List Members

Get all members of the current organization.

GET /api/v1/organizations/current/members
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": [
    {
      "userId": "user_xyz789",
      "email": "owner@example.com",
      "name": "John Doe",
      "picture": "https://lh3.googleusercontent.com/...",
      "role": "owner",
      "status": "active",
      "joinedAt": "2024-01-01T00:00:00Z",
      "lastActiveAt": "2024-01-15T10:00:00Z"
    },
    {
      "userId": "user_abc123",
      "email": "member@example.com",
      "name": "Jane Smith",
      "picture": "https://lh3.googleusercontent.com/...",
      "role": "member",
      "status": "active",
      "joinedAt": "2024-01-10T00:00:00Z",
      "lastActiveAt": "2024-01-15T09:00:00Z"
    }
  ]
}

Update Member Role

Change a member's role in the organization.

PUT /api/v1/organizations/current/members/:userId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "role": "admin"
}

Request Body:

Field	Type	Required	Description
role	string	Yes	New role: owner, admin, member, viewer

Response:

{
  "success": true,
  "data": {
    "userId": "user_abc123",
    "role": "admin",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Role Permissions

Role	Description
owner	Full access, billing, can delete organization
admin	Manage members, settings, all resources
member	Create and manage backups, schedules, projects
viewer	Read-only access

Remove Member

Remove a member from the organization.

DELETE /api/v1/organizations/current/members/:userId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Member removed successfully"
}

Create Invitation

Invite a new member to the organization.

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

{
  "email": "newmember@example.com",
  "role": "member"
}

Request Body:

Field	Type	Required	Description
email	string	Yes	Invitee's email address
role	string	No	Role to assign (default: member)

Response:

{
  "success": true,
  "data": {
    "id": "invite_abc123",
    "email": "newmember@example.com",
    "role": "member",
    "status": "pending",
    "expiresAt": "2024-01-22T11:00:00Z",
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

List Invitations

Get all pending invitations.

GET /api/v1/organizations/current/invites
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": [
    {
      "id": "invite_abc123",
      "email": "newmember@example.com",
      "role": "member",
      "status": "pending",
      "expiresAt": "2024-01-22T11:00:00Z",
      "createdAt": "2024-01-15T11:00:00Z",
      "invitedBy": {
        "id": "user_xyz789",
        "email": "admin@example.com"
      }
    }
  ]
}

Cancel Invitation

Cancel a pending invitation.

DELETE /api/v1/organizations/current/invites/:inviteId
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Invitation cancelled"
}

Resend Invitation

Resend an invitation email.

POST /api/v1/organizations/current/invites/:inviteId/resend
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "invite_abc123",
    "email": "newmember@example.com",
    "resentAt": "2024-01-15T12:00:00Z",
    "expiresAt": "2024-01-22T12:00:00Z"
  }
}

Get Service Account

Get the organization's service account details.

GET /api/v1/organizations/current/service-account
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "data": {
    "id": "sa_abc123",
    "name": "firebackup-service-account",
    "email": "firebackup@my-project.iam.gserviceaccount.com",
    "permissions": [
      "backups:read",
      "backups:write",
      "schedules:read",
      "schedules:write"
    ],
    "lastUsedAt": "2024-01-15T10:00:00Z",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Create Service Account

Create a service account for API access.

POST /api/v1/organizations/current/service-account
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID
Content-Type: application/json

{
  "name": "CI/CD Pipeline",
  "permissions": ["backups:read", "backups:write", "schedules:read"]
}

Request Body:

Field	Type	Required	Description
name	string	Yes	Service account name
permissions	array	No	Permission scopes

Response:

{
  "success": true,
  "data": {
    "id": "sa_abc123",
    "name": "CI/CD Pipeline",
    "apiKey": "fb_sa_xxxxxxxxxxxxxxxxxxxx",
    "permissions": ["backups:read", "backups:write", "schedules:read"],
    "createdAt": "2024-01-15T11:00:00Z"
  }
}

API Key Security

The API key is only shown once during creation. Store it securely as it cannot be retrieved later.

Delete Service Account

Delete the organization's service account.

DELETE /api/v1/organizations/current/service-account
Authorization: Bearer YOUR_TOKEN
X-Organization-Id: YOUR_ORG_ID

Response:

{
  "success": true,
  "message": "Service account deleted"
}

Organization Object

Field	Type	Description
id	string	Unique organization ID
name	string	Display name
slug	string	URL-friendly identifier
owner	object	Organization owner
settings	object	Organization settings
statistics	object	Usage statistics
subscription	object	Subscription details
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp

Error Responses

Organization Not Found

{
  "success": false,
  "error": {
    "code": "ORGANIZATION_NOT_FOUND",
    "message": "Organization not found"
  }
}

Permission Denied

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You don't have permission to perform this action",
    "details": {
      "requiredRole": "admin",
      "currentRole": "member"
    }
  }
}

Invitation Exists

{
  "success": false,
  "error": {
    "code": "INVITATION_EXISTS",
    "message": "An invitation already exists for this email"
  }
}

Cannot Remove Owner

{
  "success": false,
  "error": {
    "code": "CANNOT_REMOVE_OWNER",
    "message": "Cannot remove the organization owner. Transfer ownership first."
  }
}

Webhook Events

Event	Description
organization.created	Organization was created
organization.updated	Organization was updated
organization.deleted	Organization was deleted
member.joined	Member joined the organization
member.left	Member left the organization
member.role_changed	Member role was changed
invitation.created	Invitation was sent
invitation.accepted	Invitation was accepted

Related

• Authentication - Service account auth
• Organizations & Teams - User guide