The Structure of User Store

User Store stores four key data types:

• User data, like email address, phone numbers, names and social security numbers (national ID numbers)
• User consents, indicating which data processing purposes each user has consented to, like marketing or operations
• Policies and data transformers controlling the circumstances and the form in which data can be accessed and edited
• Definitions for custom APIs for accessing and editing that data (shown as the vault boundary above)

The user data table is built from columns and populated with user records. Each column has a primitive type (describing what the column stores, like string or boolean) and a logical type (describing what the column represents, like address or phone number). Columns can store a single data value or multiple values, in which case they are called array columns.

User consents describe the purposes for data processing that a given user has consented to. Purposes have names like "marketing" or "analytics", and map to the data processing purposes described in your privacy policy or terms of service. You can define your own set of purposes to use in the Purposes table of the User Store page in Console.

Users can give and revoke consent for a particular purpose for any individual piece of data. For example - they might consent to email marketing for one email address, but not another. As such, consents are granular: they are stored per data value.

User Store allows you to define custom APIs, called accessors (for reading data) and mutators (for writing data) - see below for more detail. Access policies (like IsRoleEngineer and IsIPTrusted) describe a set of rules around reading and writing data. Policies control the circumstances in which data can be retrieved from and written to the store. Data transformers (like BirthdayToAge or PhoneToAreaCode) obscure, minimize or tokenize outbound data for a given use case.

Reading Data

Data can be retrieved from the store using accessors (custom read APIs that you define). Accessors are intended to be use-case specific, e.g.GetEmailForMarketing or GetNameAndPhoneForSupport. They enforce data usage policies and minimize outbound data from the store for their given use case. Each accessor is associated with a user record selector, a set of columns, a set of data transformers, a purpose, an access policy and an optional token resolution policy (see below). The user record selector is a SQL-like clause that specifies which records the accessor should return data for, based on an array of values that are passed at execution time. The columns indicate which data fields the accessor will pull. Each column is associated with a transformer, which transforms, minimizes or obscures the outbound data from that column. The purpose indicates what the accessor will be used for, e.g. marketing. The accessor will filter out user records where the user has not consented to the specified purpose. The access policy determines the circumstances in which the data can be retrieved.

Writing Data

New data can be written to the store using mutators (custom write APIs that you define). Examples of mutators are SetProfile and SetEmailAndPhoneNumber. Each mutator is associated with a user record selector, a set of columns, a set of validators and an access policy. The record selector is a SQL-like clause that specifies which records the mutator should edit data for, based on an array of values that are passed at execution time. The columns indicate which data fields the mutator will edit. Each column is associated with a validator, which is a special data transformer that validates the incoming data and may transform it before saving it to the columns in the store. The access policy determines the circumstances in which the write is allowed.

Tokenizing Data

When using an accessor to retrieve data from the store, it is possible to tokenize the data. When you tokenize a piece of sensitive data, you replace it with a secure (but resolvable) reference token. Tokenization differs from other forms of data transformation: it allows an employee or service with sufficient permissions to resolve the token back into the raw data.

The token is generated from the accessor's transformer code. It is common to generate tokens randomly and/or to match the format of the raw data so that the token can be used in place of the data without causing validation errors. For example, you might transform an email address like [email protected] to [email protected]. The token is associated with a separate token resolution policy which controls the circumstances in which the token can be exchanged for the original raw data. When an application or employee needs the original data, it can request to exchange the raw data from the tokenization service. If the resolution access policy is met, the raw data is returned. Once the purpose for which the data was retrieved is achieved, the raw data should be discarded.