Key Concepts for Circle REST API

Key Concepts

Circle’s security architecture addresses the fundamental weaknesses of today’s cloud-native application and network architectures, with multiple breakthrough innovations – all without sacrificing the efficiency and innovation of the cloud, while ensuring data security and privacy.  Conceptually, Circle consists of a small number of entity types. Most, but not all of these are represented as classes in the API.


A Circle is a private network of unique devices, tied to users who are invited and added by a Circle Owner.   Every device that joins a Circle through a process of Peer Mediated Authentication shares a unique AES 256 encryption key, which protects all of the data within it.  This includes user data and metadata used to communicate between devices in Circles.  Thus, Circles are not only secure, they are totally private, with no visibility for outside actors into the contents, users or activities within them.

Circle Members: Devices and Their Users

A Circle Member is a user with one or more unique devices, that is invited to a Circle by the Circle Owner.  A Member usually is, but does not have to be a human user.   Circles could, for example, be composed of a human Circle Owner and a set of IOT devices that are Members of the Circle.

Circle manages devices and their users through the concept of a Member.  A Member consists of a user and all of their unique devices that are part of a Circle. 

A Member is not an API entity, but participation in a Circle operates at the level of Members. For example, the WhoAmI API call returns a member ID and all of its associated Devices – essentially a Member.   All users, devices, and content inside each Circle are totally anonymous outside of the Circle – to us or anyone else.  

Circle Owner

A Circle Owner is a user who creates and administers Circles,, and secure digital containers called Topics. A Circle Owner can create a Circle and a Topic within that Circle, and place and exchange information securely within the Circle and Topics. Circle Owners can invite other users into a Circle or a Topic to:

  1.  exchange data - including strings, files, complex objects or any structured or non structured data
  2. exchange messages - for both communications and to trigger actions.

In essence, a Circle Owner can define and create on the fly - a network of devices in which the communication and information exchange is totally secure and private, but accessible to each device / member and your application.

Circle Secure Capsules

Every Circle can create and contain an unlimited number of Secure Digital Capsules, which are an information container or folder. In the API Methods, we call these Topics.  Topics are groupings of information that you can share within a Circle. From the standpoint of data security and privacy,  Topics can be public (the default) or private.

  • Public Topics share the same encryption key as that of the Circle to which it belongs so all devices and members of a Circle have access to all the data in that Topic.
  • Private Topics each have their own encryption key that is different from the encryption key of the Circle to which it belongs. As a result, a private Topic can contain data, messages, user identities, and metadata that are protected and shared only among a unique subgroup of the Circle.

A Topic can contain almost any data. You can use Topics to organize information-sharing rights to connect groups within a company, or to share specific information with specific teams.

Distributed Multi-factor Authentication

 A Circle is created by a Circle Owner (the Circle initially exists with the Circle Owner as its only member). The Circle Owner can then invite others into that Circle. When a Circle Owner wants to add Members to the Circle, they add them by inviting and authenticating them. The Circle Owner shares two pieces of information with the Member invitee:

  1. Code 1 (Invitation ID)
  2. Code 2 (Authorization Code)

This enables the Circle Owner to invite and authorize the devices of  Circle Members that are being invited.   Once authorized, the unique AES 256 key for the Circle or Digital Capsule / Topic that has been created is shared using standard secure PKI exchange.   When this process is completed,  all devices in the Circle now have the same unique key - and no other devices or Cloud servers in the world do.

  •  There is no cloud server containing credentials, user identities, or otherwise - no central authority of any kind.
  • All data and meta-data about the users in each Circle is contained within the Circle.  

There is no point of attack to capture, spoof, impersonate, steal or otherwise break the authentication.   To get inside the CIrcle, the attacker must be personally invited and authenticated by the Circle Owner.

Encryption Key Management

Circle handles all aspects of the creation, management and protection of encryption keys in a robust and secure way so that developers do not have to worry about this.   Here are some of the most important things to know.

  • Each device has an RSA public/private key pair; these keys are used to securely share the AES keys between different devices that are part of the Circle or the Topic.
  • Each Circle and Private Topic has a unique AES256 key that is used to encrypt all messages and data stored in the Circle and in the Topic. 
  • AES keys are never seen in unencrypted form outside the device.
  • Private keys and AES keys are securely stored on the device using the device operating system’s crypto-systems (for example, keychain or TPM).