Status

Owner	Lead	Doc Status	Product Status	Last Update	Version	Release	Phase
Mendy	Esti	In Progress	Up Next	04.03.2024	0.01	Internal	Alpha

note

These details are only updated with each release, for more acurate updates and keeping track of progress, see the task in GitHub.

Description

The account serves as a source of ownership and truth, here the client can keep data about thier users, BackBone will also have its users to ensure information provided to clients are acurate. Users can keep all thier details in order to enjoy all the features our APIs and what the client offers them.

Reminders

Links & Resources

Research

note

the research listed here is spesifict to the User (Account) feature, for research related to the general BackBone development see the Research document.

In the course of our research, we discovered many tools that will help us achieve the project goal. This document contains the research that was done for both, thus it is the [** Project**] Research. To read about the conclusions drawn from the research one should read the complete Project Description and its accompanying documents.

Technical

Question - How do we get data from arenas to form the arena layout and map the devices?

Answer - In our research we found many [API]s that give us much information but they are all very limited and expensive.
We

Conclusion - How do we get data from arenas to form the arena layout and map the devices?

Sources

[test]

Business

User Stories

Persona One

Update Coming Soon

As a busy user I don’t want to watch but rather listen to a podcast, however, when I hear a voice I don’t recognize, I want to take a glance at my phone to see a name and/or photo of who is talking or maybe ask the built-in “AI/assistant”.

Flows

Personas

Libraries

Actions
Stacks
Components
Assets
Apps

Features

Below is a list of features that will be utilized in order to deliver the best account features and functionalities. The details bellow are not comprehensive feature details but rather, describe how the features will be utilized within the account, for further details, please see the individual feature documentation.

Authentication

Not all accounts will requier auth, indevidual accounts will need to authenticate however the client can indecate what account types do not need auth and will instead be accessed though indevidual accounts. If auth is not reqried than access is reqied and vs.
Access

If the account type is not "indiviual" the account will not have an auth method and thefore will reqesre access. This will be a sub-collection within the account document that will hold the account, group, etc IDs of anyone who has access to this account.
[Account recovery]
[Flags]

if an account seems suspisus it should be flaged so that any channel, content, comments or otherwise can be monitored
Anonomus User (Account) 2.0

On the document we want to keep all the important data, the first fetch and fast to access, all secondary data should be stored on a subcollection and fetch sepratly (if this is cost sfective)

User Accounts should be a top level collection, each account will generate a new document within the "Accounts" collection.

Account

- Account
- - Acount 1
- - - type (offer a fea default options that the client can configure as well as custome options or offer numbered types and allow te client to give each type a title, this will enable the client to offer difrent feature or access levels based on account types)
- - - email
- - - number
- - - legal name (if connected wit a / our identity API this will allow for name/identity varification, useful for saftly and fintech and fraud protection)
- - - age (also opcinaly connect with identity api for varification)
- - - dob (also opcinaly connect with identity api for varification)
- - - varified (true, false)
- - - created (date)
- - - timezone
- - - langages
- - - contact detail

Names

    - names
    - - name 1
    - - - type (legal, nicname, madename, etc)
    - - - name
    - - - laguadge
    - - - created (date)
    - - - varified (true, false)
    - - - varified source (api id)

Identification

    - id
    - - id 1
    - - - type (licence, passport, health card, etc)
    - - - issuer (US gov)
    - - - id number
    - - - status: verified
    - - - issued (date)
    - - - experation (date)
    - - - Verify provider: (api id)
    - - - Verify date: log id
    - - - image
    - - - id_proof`

Sessions

    - Sessions
    - - Section #1
    - - - auth type (OTP, Google, Apple, Normal)
    - - - device_type (Android, IOS, Web)
    - - - device_token
    - - - location
    - - - activated (date)
    - - - status (active, inactive)
    - - - inactive (date)

Locations

Preferences

- prefrences
- - communication
    - - - method (push, email, text)
    - - - default (true, false)
    - - - allow (true, false)
    - - - block (true, false)
    - - - level (all, update, security, system)
    - - - channels (id, id, id)
    - - privacy
    - - - allow (true, false)
    - - - block (true, false)
    - - - allow user data collection (true, false)
    - - - allow user data share (true, false)
    - - - allow user data anonymize (true, false)
    - - - allow user data deletion (true, false)

Accounts

`GET /account`

Returns the caller's own account profile.

Response `200 OK`

{
  "uid": "abc123",
  "type": "personal",
  "status": "active",
  "verified": false,
  "createdAt": "2026-01-15T09:00:00.000Z",
  "updatedAt": "2026-01-15T09:00:00.000Z",
  "lastLoginAt": "2026-01-15T09:00:00.000Z",
  "email": "alice@example.com",
  "languages": ["en", "ru"]
}

Field	Type	Description
`uid`	`string`	Firebase UID — same as Firestore document ID
`type`	`string`	`personal` \| `organization`
`status`	`string`	`active` \| `blocked` \| `inactive` \| `expired`
`verified`	`boolean`	Whether the account is verified
`email`	`string?`	Present when the Firebase token carries an email
`phoneNumber`	`string?`	Present when the Firebase token carries a phone number
`lastLoginAt`	`string?`	ISO-8601 timestamp of the most recent `POST /auth/sync`
`timezone`	`string?`	IANA timezone identifier (e.g. `Europe/Berlin`)
`languages`	`string[]`	Preferred languages as BCP-47 codes

Error `404 Not Found`

Returned when POST /auth/sync has never been called for this UID.

{
  "error": "NotFound",
  "message": "Account not found. Call POST /auth/sync first."
}

`POST /account/org`

Creates a new organization account in Firestore (type organization). The authenticated caller is automatically written as the owner in the new account's access subcollection.

Request

No body required.

Response `201 Created`

{
  "uid": "Xk9mP2qRvN",
  "type": "organization",
  "status": "active",
  "verified": false,
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T10:00:00.000Z",
  "languages": []
}

The returned uid is the Firestore auto-generated document ID for the new organization account. Use this value as X-Account-Id in subsequent requests to act on behalf of the organization.

`GET /account/access`

Lists every access entry in accounts/{uid}/access — i.e. the list of users who have access to the caller's own account.

Response `200 OK`

[
  {
    "accountId": "abc123",
    "granteeId": "abc123",
    "role": "owner",
    "grantedAt": "2026-01-15T10:00:00.000Z"
  },
  {
    "accountId": "abc123",
    "granteeId": "def456",
    "role": "member",
    "grantedAt": "2026-01-16T08:30:00.000Z"
  }
]

Field	Type	Description
`accountId`	`string`	UID of the account that owns this entry
`granteeId`	`string`	UID of the user who was granted access
`role`	`string`	`owner` \| `admin` \| `member`
`grantedAt`	`string`	ISO-8601 timestamp when the access was granted

`GET /account/access/[granteeId]`

Returns the single access entry for granteeId in the caller's account.

Response `200 OK`

{
  "accountId": "abc123",
  "granteeId": "def456",
  "role": "member",
  "grantedAt": "2026-01-16T08:30:00.000Z"
}

Error `404 Not Found`

{
  "error": "NotFound",
  "message": "No access entry found for the given granteeId."
}

`POST /account/access/[granteeId]`

Grants access to granteeId on the caller's account (or the organization account identified by X-Account-Id).

Request body

{ "role": "member" }

role is optional — defaults to member when omitted.

Value	Description
`owner`	Full control, including granting/revoking access for others
`admin`	Can manage content; cannot manage access
`member`	Read-only access

Response `201 Created`

{
  "accountId": "abc123",
  "granteeId": "def456",
  "role": "member",
  "grantedAt": "2026-01-16T08:30:00.000Z"
}

curl example

curl -X POST https://colibri-api-643619291153.me-west1.run.app/account/access/def456 \
  -H "Authorization: Bearer <ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

`DELETE /account/access/[granteeId]`

Revokes the access entry for granteeId. Succeeds silently even if the entry does not exist.

Response `204 No Content`

No body.

Error codes

Code	Meaning
`400`	Missing or invalid request body
`401`	Missing or expired Firebase token
`403`	No access entry found for the given `X-Account-Id`
`404`	Resource not found
`405`	Wrong HTTP method
`500`	Unexpected server error

Error response body:

{
  "error": "ErrorCode",
  "message": "Human-readable description."
}

Status​

Description​

Reminders​

Links & Resources​

Research​

Technical​

Business​

User Stories​

Flows​

Personas​

Libraries​

Actions​

Stacks​

Components​

Assets​

Apps​

Features​

Authentication​

Access​

[Account recovery]​

[Flags]​

Account​

Names​

Identification​

Sessions​

Locations​

Preferences​

Accounts

GET /account​

Response 200 OK​

Error 404 Not Found​

POST /account/org​

Request​

Response 201 Created​

GET /account/access​

Response 200 OK​

GET /account/access/[granteeId]​

Response 200 OK​

Error 404 Not Found​

POST /account/access/[granteeId]​

Request body​

Response 201 Created​

curl example​

DELETE /account/access/[granteeId]​

Response 204 No Content​

Error codes​

Status

Description

Reminders

Links & Resources

Research

Technical

Business

User Stories

Flows

Personas

Libraries

Actions

Stacks

Components

Assets

Apps

Features

Authentication

Access

[Account recovery]

[Flags]

Account

Names

Identification

Sessions

Locations

Preferences

`GET /account`

Response `200 OK`

Error `404 Not Found`

`POST /account/org`

Request

Response `201 Created`

`GET /account/access`

Response `200 OK`

`GET /account/access/[granteeId]`

Response `200 OK`

Error `404 Not Found`

`POST /account/access/[granteeId]`

Request body

Response `201 Created`

curl example

`DELETE /account/access/[granteeId]`

Response `204 No Content`

Error codes