Consent Docs

Identifier rules

Every rule the API applies to an identifier in one place, from the types and how each is matched to the limits, proofs and errors.

Reference4 min readFor web, backend and mobile developers

The rules the API applies to every identifier you send. For the ideas behind them, see Identifiers. For a worked example, see Record and withdraw consent by email, phone or session id.

Types#

subjectType The service prepares the text by From a browser or an app Example
EMAIL Removing spaces at both ends, then putting it in lower case Needs an identity proof kavya.menon@example.in
PHONE Removing spaces at both ends Needs an identity proof +919846011223
USER_ID Removing spaces at both ends. Case is kept. Needs an identity proof usr_8f2K1xQz
DEVICE_ID Removing spaces at both ends. Case is kept. An app records under the device id it made. Linking one needs a proof. dev_5Tq8Lm2w
SESSION_ID Removing spaces at both ends. Case is kept. No proof sess_4Hq9x2
COOKIE_ID Removing spaces at both ends. Case is kept. No proof. The runtime makes it. Made by the runtime

A write that leaves out subjectType is kept as COOKIE_ID. The calls on a person, such as findSubject and withdrawSubject, require it.

Prepare values yourself#

The service hashes the prepared text and changes nothing else. Prepare each value the same way on every call.

Type Do this before you send it
EMAIL Remove spaces and put it in lower case, so your own tables agree with the service.
PHONE Write it in E.164, with the country code and no spaces: +919846011223. 09846011223, +91 98460 11223 and +919846011223 are three different people to the service.
USER_ID Use a stable id that never changes for the person, with a prefix such as usr_.
SESSION_ID Use an id that names the session and signs nobody in, with a prefix such as sess_. Never send a session cookie or a login token.
DEVICE_ID Use the id the mobile SDK gives you, or your own installation id.

The text decides the match#

The keyed hash is made from the prepared text alone. The type only decides how the text is prepared. This has two effects:

  • abc123 sent as a USER_ID and abc123 sent as a SESSION_ID are the same person to the service. Prefix your ids so that values of two types never meet.
  • Kavya.Menon@example.in sent as an EMAIL matches kavya.menon@example.in. Sent as a USER_ID, it keeps its capitals and does not.

What each call matches#

Call Records it reaches
recordConsent The record for the same form and the same prepared text, if one exists and is not erased. Otherwise it creates one. Linked identifiers are not followed, so a write under a linked email address makes a second record.
updateConsent, withdrawConsent The one record named by consentId.
linkIdentifiers Every record held under the subject or linked to it that is not erased.
findSubject, exportSubject Every record held under the identifier or linked to it. Erased records stay in the list with erasedOn.
withdrawSubject The same records, except those already withdrawn or erased.
eraseSubject The same records, except those already erased.
checkConsent Records held under the identifier or any alsoKnownAs entry, and records linked to any of them.

A test key reaches only records written with a test key, and a live key only live records.

Erasing a record deletes its linked identifiers. After that, the record is found only by the identifier it was recorded under.

Limits#

Field Limit
subjectId 1 to 255 characters.
identifiers on a write or a link call Up to 5. Two entries with the same type and prepared text are refused.
alsoKnownAs on a check Up to 4. Each one counts against the check budget.
identityProof and proof 64 hex characters.
reason on a withdrawal or erasure Up to 500 characters.
metadata Up to 8,192 bytes of JSON.

Identity proofs#

A browser or an app holds a publishable key, which is public. To use a person's real identity there, your server signs it:

proof = hex( HMAC-SHA256( identity secret, subjectType + ":" + subjectId ) )
  • The proof covers the exact text you send. It is not trimmed or put in lower case, so sign the value after you prepare it.
  • A browser or an app needs a proof to record under an EMAIL, PHONE or USER_ID.
  • It needs one to link an EMAIL, PHONE, USER_ID or DEVICE_ID. A SESSION_ID or COOKIE_ID needs none.
  • A secret key never needs a proof.
Node.jsJavaScript
import { identityProof } from '@piedap/consent/server';

const proof = identityProof(
  process.env.PIEDAP_IDENTITY_SECRET,
  'EMAIL',
  'kavya.menon@example.in',
);
Python
import os

from piedap_consent import identity_proof

proof = identity_proof(
    os.environ["PIEDAP_IDENTITY_SECRET"], "EMAIL", "kavya.menon@example.in"
)

Scopes for calls on a person#

Call Scope
recordConsent, updateConsent, withdrawConsent, consentPortalLink None beyond a secret key
findSubject subjects:read
exportSubject subjects:export
linkIdentifiers subjects:link
withdrawSubject subjects:withdraw
eraseSubject subjects:erase
checkConsent consent:check

Grant a scope under Scopes on the key in Install.

Errors#

Status Code When
400 None. The message is a list subjectId is empty or longer than 255 characters, subjectType is not one of the six types, or identifiers has more than 5 entries or a repeat.
400 METADATA_TOO_LARGE metadata is over 8,192 bytes of JSON.
403 IDENTITY_PROOF_REQUIRED A browser or an app recorded under an EMAIL, PHONE or USER_ID without a matching proof.
403 IDENTIFIER_PROOF_REQUIRED A browser or an app linked an EMAIL, PHONE, USER_ID or DEVICE_ID without a matching proof.
403 SCOPE_REQUIRED The key lacks the scope the call needs, or a publishable key called a person endpoint.

An empty records list from findSubject and withdrawn: 0 from withdrawSubject are not errors. Nothing is held under that identifier, or nothing was left to withdraw.

↑↓ to move, Enter to open