The format atServers use to store and share data.

At Atsign, whenever we mention the word "key" we are normally talking about a cryptographic key.

The main exception being the atKey, this is the "key" of a "key value pair" that makes up every atRecord.

It's unfortunate that the word "key" is polymorphic in computer science, and we have tried in the past to move to other words, but we have decided to stick with keys and the developer will have to understand the context of cryptographic key or key value pair (sorry!)

atRecords are the data records that are stored by the atServers. We use the common key-value pair format.


An atKey is the identifier half of the "key-value" pair. Similar to the primary key of a tabular database, the atKey must be a unique string which represents the data.

There are 5 different types of an atKey.



Store and share public data which can be seen by anyone.


Store data which can only be seen by the owner.


Store and share private data which can only be seen by the owner and intended recipient.


Store data which can only be seen by the owner, hidden by default.


Cache shared data from other atSigns for performance and offline mode.

Structure of an atKey

[cached:]<visibility scope>:<record ID><owner’s atSign>


A marker for whether it is a cached key or not.

Visibility Scope

A marker for who has access to the key.

Record ID

A unique string used to represent the atRecord.

Owner's atSign

The owner (i.e. creator's) atSign for that particular atRecord. The shared by atSign of an atRecord is synonymous to the owner atSign of an atRecord.

Rules for atKeys
  1. Length of an atKey should not be more than 240 characters (a limitation of the current implementation of the atServer, not a protocol limitation)

  2. A maximum of 55 7-bit characters for the atSign (unicode is translated to UTF-7)

  3. Allowed characters in an entity are: [\w._,-"']

  4. Namespace is mandatory in the current implementation of the protocol i.e entity must follow the notation: <identifier>.<namespace>

  5. Cached atKeys should have a different owner than the current atSign

  6. Visibility scope and owner cannot be the same for a shared atKey

  7. Reserved atKeys cannot be modified or notified

  8. For newly created atKeys, the owner must match the current atSign

Reserved atKeys

The following is a list of reserved atIKeys which the atServer requires to function.

Don't try to delete or overwrite these keys, the atServer cannot function without them.

  • privatekey:at_pkam_privatekey

  • privatekey:at_pkam_publickey

  • public:publickey

  • privatekey:privatekey

  • shared_key

  • privatekey:self_encryption_key

  • signing_privatekey

  • public:signing_publickey

  • privatekey:at_secret

  • privatekey:at_secret_deleted

Example atKeys

Public atKey

  1. A public atKey with a record id of location shared by @alice. This atKey typically holds public data that any atSign can access.


  1. A public atKey with a record id of publickey shared by @bob. Note that this is a reserved atKey.


Private atKey

  1. A private atKey with a record id of pk1 shared by @alice.


Shared atKey

  1. A shared atKey with a record id of phone shared with @bob, shared by @alice.


  1. A shared atKey with the record id of name, a namespace of wavi, shared with @alice, and shared by @bob.


Internal atKey

  1. An internal atKey with a record id of _latestnotificationid, namespace of at_skeleton_app and is shared by @alice.


Cached atKey

  1. A cached atKey with a record id of phone, shared with @bob, and is shared with @alice.



Metadata of the atRecord is also stored and describes the following properties of the atValue.

Meta Attribute

Auto create?




A Date and Time derived from the ttb (now + ttb). A Key should be only available after availableFrom.



Indicates if a cached key needs to be deleted when the atSign user who has originally shared it deletes it.



atSign that has created the key



Date and time when the key has been created.



A Date and Time derived from the ttl (now + ttl). A Key should be auto deleted once it expires.



True if the value is a binary value.



True if the key is cached.



True if the value is encrypted.



A Date and Time derived from the ttr. The time at which the key gets refreshed.



atSign of the user with whom the key has been shared. Can be null if not shared with anyone.



Date and time when the key has been last updated.



Time to birth in milliseconds.



Time to live in milliseconds.



Time in milliseconds after which the cached key needs to be refreshed. A ttr of -1 indicates that the key can be cached forever. ttr of 0 indicates do not refresh. ttr of > 0 will refresh the key. ttr of null indicates the key is impossible to cache, hence, refreshing does not make sense (which has the same effect as a ttr of 0).


Text or binary values can be saved in an atServer.

Small objects are fine to use the atServer but large objects should be used by reference.

For example, derive a new encryption key, encypt a file, upload that file to location, then notify other atSigns of the location and the encyption key. This is how atmospherePro works.

The size of the value saved in an atServer is bound by the atProtocol's config parameter "maxBufferSize".

Last updated

© 2023 Atsign