Skip to end of metadata
Go to start of metadata

Accounts help the system figure out what users and devices exist in the system, whom they belong to, and whether an account is active. An explanation of some of the key ways we use accounts is below.

Accounts are used within the system to keep tenant data independent from other tenants. This allows for common usernames (like "admin") to exist for each account, and also allows for moving individual tenant data without disrupting other tenants.

Account and User Look-up

When a user is logging in, the global accounts database is used to figure out what account they are logging into. To make things easier for users to remember, we utilize a friendly account name, which the user must enter. We then search all documents in the accounts database and compare their "name" field against what was entered. If we find a match and the account is enabled, we lookup the user's credentials in the specific account database.

Device Registration and Outbound Calling

When a device registers or makes a call, the device transmits it's DNS realm to our servers. We utilize the domain name to figure out which account the device belongs to. We then check to make sure the username and password presented by the device match a device document within that specific account.

The process is exactly as shown above except the domain name is used to find the account instead of a friendly account name.

In the above example, we'd use the "realm" field from the account document and match it against the DNS name the phone sends in from it's authentication header or From: header to find the correct account in the database. Then we'd lookup the phone's SIP username and SIP password.

Sample Account Document

Below is an example account document. This would go into the account database itself. In this example:

  • The account's ID is 12341234123412341234123412341234
  • The friendly name (which users would login with as their "Account Name") is 2600hz Master
  • The realm (which devices would use to register) is
Sample Account Document
   // Account's ID number, used in API calls and everywhere else
   "_id": "12341234123412341234123412341234",

   // DNS name for all devices within this account
   "realm": "",

   // A friendly name for the account, used when logging in
   "name": "2600hz Master",

   // The API key/password for use with this account
   "pvt_api_key": "12345678904236634ba82da9a5b0aa9513605124f19955c0d4be801234567890",

   // A list of parent accounts who are allowed full access to this account's data
   "pvt_tree": [

   // A copy of the account ID (private). This should match the _id field above
   "pvt_account_id": "12341234123412341234123412341234",

   // The database-formatted version of the Account ID, note the %2F which is a slash
   "pvt_account_db": "account%2F12%2F34%2F1234123412341234123412341234",

   // Whether the account is enabled or not (impacts sub-accounts!)
   "pvt_enabled" : true,

   // The document type. This is very important and identifies this entire document as an account
   "pvt_type": "account",

   // The version of this type of document. Used internally for tracking upgrades
   "pvt_vsn": "1"

This document would be stored in two places:

  • Within the account itself. This version is considered the master or primary version
  • The accounts database (which is used for global lookups). This version is considered a copy

Running your own cluster?

You can manually change account data in the database, but you must make sure the account data exists in both the accounts database and within the database for the account itself. A sample of an account definition document is above.



  • No labels