Team

Owner	Lead
Mendy	Sergey

Status

Doc Status	Product Status	Last Update	Version	Release	Phase
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, we keep only account related data, as public facing data will be part of the Profile.

Reminders

Links & Resources

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 Stories

Persona One

Update Coming Soon

Flows

Personas

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

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

Team​

Status​

Description​

Reminders​

Links & Resources​

Research​

Technical​

Business​

User Stories​

Flows​

Personas​

Features​

Authentication​

Access​

[Phone Auth]​

[Keys]​

[Multi Factor Auth]​

[Annonimus Account]​

[Account recovery]​

[Flags]​

Data

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​

Team

Status

Description

Reminders

Links & Resources

Research

Technical

Business

User Stories

Flows

Personas

Features

Authentication

Access

[Phone Auth]

[Keys]

[Multi Factor Auth]

[Annonimus Account]

[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