Accounts

Accounts can be used in two ways thought the account type, personal and business (more types to be added later), at the core they all work the same, we use the Access feature to determin what the account can access.

Task Chat Branch API

Status & Details

Development Status

Docs	Backend	Frontend
In Progress	In Progress	In Progress

Release Status

Version	Release	Phase	Channels
0.01	Internal	Alpha	-

Team

Owner	Lead
Mendy	Sergey

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, we keep only account related data, as public facing data will be part of the Profile.

Reminders

Links & Resources

Research

Research

note

the research listed here is spesifict to the Account feature, for research related to the general Colibri development see the Research document.

Technical

---

Question - Answer -

Conclusion -

Sources

• [test]

---

Business

User Focused

User Stories

Persona One

Update Coming Soon

Flows

Personas

Features & Functions

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.

• [Phone Auth]

  Allow users to authenticate user thier phone number

• [Keys]

  Allow users to create a key and use for auth

• [Multi Factor Auth]

  Allow users to opted into MFA

• [Annonimus Account]

  Generate an anonimus account for all visitor, hold data for 15 days

• [Account recovery]

  should the user lose access to thier account (e.g. forgot password, no ket access, hacked, etc), provide a way to identify the user and regain access.

• [Flags]

  if an account seems suspisus it should be flaged so that any channel, content, comments or otherwise can be monitored

Data

Data

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)

API

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."
}