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.
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:
abc123sent as aUSER_IDandabc123sent as aSESSION_IDare the same person to the service. Prefix your ids so that values of two types never meet.Kavya.Menon@example.insent as anEMAILmatcheskavya.menon@example.in. Sent as aUSER_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,PHONEorUSER_ID. - It needs one to link an
EMAIL,PHONE,USER_IDorDEVICE_ID. ASESSION_IDorCOOKIE_IDneeds none. - A secret key never needs a proof.
import { identityProof } from '@piedap/consent/server';
const proof = identityProof(
process.env.PIEDAP_IDENTITY_SECRET,
'EMAIL',
'kavya.menon@example.in',
);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.