Sign in

Identities of data subjects

In the Privacy Services, data subjects have certain data sets connected to them within a project:

  • Permission requests (consent & objections)
  • Privacy requests (delete, access & portability)
  • Permission state (a combined view of given permissions)

Identities represents the data subjects within your project and allows your service to:

  • Trust that permissions and privacy requests are stored on the correct data subject
  • Have the possibility to change identifiers over time using aliases without resulting in the creation of ghost data subjects and incomplete permission states and privacy request history
  • Allow data subjects to also be parties in the data processing flow, as data recipients or data controllers, depending on the use cases the Privacy Services is used for
  • Use specific endpoints for access and erasure of all data we have on specific data subjects, thus complying with GDPR within the Privacy Services itself

Modeling a data subject

For the sake of minimising scope and complexity, we have chosen to model data subjects around a simplified identity model. This makes the API flexible enough and allows it to be extended later for other use cases.

Conceptually, identities represent users and things. Everything has an identity and most use cases need to know the identity of the source and owner of generated data. Identities are identifiable by unique identifiers. Identities have in some cases aliases, meaning that the same entity (user or thing) may have more than one identifier or change identifiers over time.

Create an identity

Creates an identity that represents a data subject within a project

POST /privacy/v2/projects/{project_id}/identities

Update an identity

Updates a specific identity object

PUT /privacy/v2/projects/{project_id}/identities/{identityId}

Delete an identity

Delete a identity and all its data in the system

DELETE /privacy/v2/projects/{project_id}/identities/{identityId}

Get an identity

Return a specific identity object.

GET /privacy/v2/projects/{project_id}/identities/{identityId}

Return all data related to a specific identity object.

GET /privacy/v2/projects/{project_id}/identities/{identityId}/data

Lookup an identity

In some use cases, a client needs to lookup the identity of a data subject using their own internal reference (referenceID) or one of the identity aliases. This endpoint will return the identity object that has a 100% match on referenceID or aliases identifiers.

GET /privacy/v2/projects/{project_id}/identities/aliases/{alias}

The alias parameter in the path must be URL encoded and consist of type and identifier string used in aliases for the identity you are looking for. Format: {type}:{identifier}

Example: If you are looking for an identity that has an alias of the Norwegian national ID type and value 18117700000, the alias lookup string will be urn:tdx:nonationalid:18117700000

Using it in the path it must be URL encoded like:

GET /privacy/v2/projects/{project_id}/identities/aliases/urn%3Atdx%3Ano_national_id%3A18117700000

Schema

This section specifies the identity schema

Field Type Description Comments
projectId string The ID of the project
identityId string The identity ID generated by us
aliases JSON array An array of JSON objects  containing aliases Aliases are described in the section below
created timestamp The time this identity was created in the system
updated timestamp The time this identity was last updated the system  

Aliases

The aliases array can be used to connect other identifiers to the same identity. It is a method used to connect two or more reliable identifiers used for the same data subject over time, effectively allowing the consumers of the Privacy Services to identify and treat different sets of data subject identifiers as one.

Example

When registering consent during a purchase process, the client might not have created a customer entry in their databases yet, the only identifier they might have is the user’s personal number. The client would then create an identity via the privacy services identities endpoint and store the data subject’s permissions with the permissions endpoint. At this point in time the client doesn’t have the internal customer ID yet.

Once the order is processed and a customer entry created in the client’s systems, the client can call the identities endpoint updating their referenceID for the user with their internal customer id and/or add any other reliable identifiers used for that same data subject as aliases as needed.

All aliases must be typed with Telia Division X’s Uniform Resource Name (URN) format, allowing us and consumers of the API to programmatically distinguish between identifiers types (example: “urn:tdx:no_national_id”).

URN specification for "tdx" NID

Namespace ID: tdx

Declaration of syntactic structure: The Namespace Specific String (NSS) of all URNs that use the "tdx" NID will have the following structure:

urn:tdx:{tdx-resource}:{resource-specific-string}

where the "tdx-resource" is a US-ASCII string that conforms to the URN syntax requirements and defines a specific class of resource type. Each resource type has a specific labelling scheme that is covered by "resources-specific-string", which also conforms to the naming requirements. The only exception is that the character ":" shall not be used as part of the "tdx-resource" string. This is to avoid possible confusion.

Aliases schema

This section specifies the aliases schema

Field Type Description Comments
type string The type of alias, following the Telia Division X’s Uniform Resource Name (URN) format
identifier string The alias identifier string  

Example response

GET /privacy/v2/projects/{project_id}/identities/aliases/urn%3Atdx%3Ano_national_id%3A18117700000

or

GET /privacy/v2/projects/{project_id}/identities/b1df0752-21d5-4a70-88d9-bfe9371dd175

{
  "projectId": "92f98d83-673a-469b-9a1d-b52cfa279090",
  "identityId": "b1df0752-21d5-4a70-88d9-bfe9371dd175",
  "aliases": [
    {
     "type": "urn:tdx:no_national_id",
     "identifier": "18117700000"
    }
  ],
  "updated": "2018-03-19T13:49:39.819Z",
  "created": "2018-03-19T13:49:39.819Z"
}

Intended usage

Clients will need to create an identity, representing a data subject, in Privacy Services before posting permissions or privacy requests to it. It’s important that clients store this unique identifier and use it throughout all API requests towards Privacy Services.

Clients may use the identity lookup endpoint when necessary, but its not intended for continuous lookups before another endpoint is called.