AtRecords

AtRecords are data records stored in atServers.

What are AtRecords?

AtRecords are composed of two things: AtKey and AtValue .

They are very similar to key-value pairs in a JSON file, but the "key" part follows a strict format (that is abstracted away by SDKs) and "values" which can be text or binary.

Related Atsign Protocol verbs are update, llookup, lookup, plookup, and delete. See the Atsign Protocol for more information.

AtRecords is a new concept in our Atsign Platform docs, and you may find no reference of them in our SDKs. However, you will find lots of references to AtKeys and AtValues!

AtKey 🔑

This is not to be confused with the .atKeys file . Since their names are very similar, we refer to AtKey-AtValue pairs as AtRecords.

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.

Types

There are 5 different AtKey types:

Type	Purpose
Public	Store and share public data which can be seen by anyone. Using a public AtKey indicates it stores public and unencrypted plain text.
Self	Store data which can only be seen by the author of the AtKey. Using a self AtKey indicates it stores data intended for self, and contains encrypted data with keys only itself has.
Shared	Store and share private data which can only be seen by the owner and intended recipient. Using a shared AtKey indicates it points to data that is encrypted with someone else's key package.
Private	Store data which can only be seen by the owner, hidden by default.
Cached	Cache shared data from other atSigns for performance and offline mode.

Anatomy

Below is a diagram of the anatomy of an AtKey. Learn more about key anatomy in the Atsign Protocol.

        @bob : city.address . my_app @ alice
        └─┬─┘  └─────┬─────┘ └──┬───┘  └─┬─┘
    sharedWith      key      namespace  sharedBy
    (recipient)                          (owner)

Each part of the AtKey has meaning; some mandatory and some not.

Part	Meaning
sharedWith	This AtKey is shared with this Atsign, always starts with an @ symbol
key	Mandatory. This is the name you give it
namespace	The application namespace it's part of (e.g. my_app or contacts.favourites)
sharedBy	Mandatory. The owner/author of this AtKey

Examples

Type	Example	Meaning
Public AtKey	public:location@alice	A public AtKey with a record id of location shared by @alice (@alice authored this AtKey). This AtKey is prefixed with public: which means it holds public data that any Atsign can access, even without authentication. The AtValue that this key holds is expected to be plain text.
Private AtKey	privatekey:pk1@alice	A private AtKey with a record id of pk1 shared by @alice . No other Atsign can view this key except for @alice.
Shared AtKey	@bob:phone@alice	A shared AtKey with a record id of phone, shared with @bob, and shared by @alice. The AtValue is expected to be accessible by @bob's cryptographic keys.
Internal AtKey	_latestnotificationid.at_skeleton_app@alice	An internal AtKey with a record id of _latestnotificationid, namespace of at_skeleton_app and is shared by @alice. This does not show up in scan:showHidden:true. Read more about that in Atsign Protocol.
Cached AtKey	cached:@bob:phone@alice	A cached AtKey with a record id of phone, shared with @bob and is shared with @alice. This is a key that would be expected to be cached in @bob's atServer, since bob here will be caching alice's data for faster retrieval.

Rules

• Length of an atKey should not be more than 240 characters (a limitation of the current implementation of the atServer, not a protocol limitation)

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

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

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

• Cached atKeys should have a different owner than the current Atsign

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

• Reserved atKeys cannot be modified or notified

• For newly created atKeys, the owner must match the current Atsign

Reserved AtKeys

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

• 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

Reserved namespaces

You cannot give your AtKeys certain namespaces. See our section on Namespaces regarding reserved namespaces.

AtKey Metadata

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

Meta Attribute	Auto create?	Description
availableFrom	Yes	A Date and Time derived from the ttb (now + ttb). A Key should be only available after availableFrom.
ccd	No	Indicates if a cached key needs to be deleted when the Atsign owner who has originally shared it deletes it.
createdBy	Yes	Atsign that has created the key
createdOn	Yes	Date and time when the key was created.
expiresOn	Yes	A Date and Time derived from the ttl (now + ttl). A Key should be auto deleted once it expires.
isBinary	No	True if the value is a binary value.
isCached	No	True if the key is cached.
isEncrypted	No	True if the value is encrypted.
refreshAt	No	A Date and Time derived from the ttr. The time at which the key gets refreshed.
sharedWith	No	Atsign of the individual with whom the key has been shared. Can be null if not shared with anyone.
updatedOn	Yes	Date and time when the key was last updated.
ttb	No	Time to birth in milliseconds.
ttl	No	Time to live in milliseconds.
ttr	No	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).

AtValue 🗳️

You can save text or binary values in an atServer.

While the atServer is suitable for small objects, you should handle large objects by reference.

For example, to share a large file:

1. Derive a new encryption key.

2. Encrypt the file.

3. Upload the file to a storage location.

4. Notify other Atsigns of the location and the encryption key.

This "by reference" pattern is used in applications like NoPorts to ensure efficient data transfer.

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

Each AtValue belongs to one AtKey. Its metadata specifies encryption, binary encoding, and availability.