Browser-based API¶

Description of the browser-based integration.

API flow examples¶

Retrieving a users privacy status¶

The following sequence illustrates the API calls initiated by a netID Partners CMP to establish a privacy status for an already authenticated user.

Browser based API

Read APIs¶

Sync-ID

In case the Sync-ID should be included in the API responses (if preconditions are met), the APIs must be called with the respective accept header.

Without Sync-ID: application/vnd.netid.permission-center.netid-user-status-v1+json
With Sync-ID: application/vnd.netid.permission-center.netid-user-status-audit-v1+json

Read privacy status¶

Request (incl. Sync-ID)¶

GET https://einwilligungsspeicher.netid.de/netid-user-status?q.tapp_id.eq=<TAPP_ID> HTTP/1.1
Accept: application/vnd.netid.permission-center.netid-user-status-audit-v1+json
Cookie: tpid_sec=<JWT_TOKEN>
Origin: <ORIGIN>

Response (incl. Sync-ID)¶

HTTP/1.1 200 OK
Content-Type: application/vnd.netid.permission-center.netid-user-status-audit-v1+json
Access-Control-Allow-Origin: <ORIGIN>
Access-Control-Allow-Credentials: true

{
  "status_code": "PERMISSIONS_FOUND",
  "subject_identifiers": {
    "tpid": "<TPID>"|null,
    "sync_id": "<SYNC_ID>"
  },
  "netid_privacy_settings": [
    {
      "type": "IDCONSENT",
      "status": "VALID"|"INVALID",
      "changed_at": "<TIMESTAMP>"
    },
    {
      "type": "DATASHARE",
      "status": "VALID"|"INVALID",
      "changed_at": "<TIMESTAMP>" 
    },
    {
      "type": "IAB_TC_STRING",
      "value": "<TCSTRING>",
      "changed_at": "<TIMESTAMP>"
    }
  ]
}

Response Properties¶

item	description
tpid	Users netID identifier (`tpid`). Only returned if consent "idconsent" is VALID, the `tpid` is known (i.e. user is already authenticated on the device) and status "PERMISSIONS_FOUND". Otherwise null.
sync_id	Partner specific Sync-ID of the netID user. Only returned if any "netid_privacy_settings" are present in the permission center at the time of the API call
IDCONSENT	If consent "IDCONSENT" is given, value is 'VALID' and users netID identifier (`tpid`) is returned. If consent "IDCONSENT" is revoked, value is 'INVALID'. Otherwise null.
IAB_TC_STRING	TC string stored for this `tpid` for this respective netID Partner (TAPP).

Response behavior¶

HTTP status_code	status_code	meaning
200 OK	PERMISSIONS_FOUND	Call successful. Permissions found and returned.
200 OK	PERMISSIONS_NOT_FOUND	Call successful. netID user is authenticated. No permission (privacy status) found for the given `tapp_id`. No subject_identifiers returned.
400 BAD REQUEST	NO_TPID	No tpid_sec cookie in request available. No authenticated netID user.
400 BAD REQUEST	TOKEN_ERROR	Token in cookie is expired or invalid.
403 FORBIDDEN	TAPP_NOT_ALLOWED	TAPP `tapp_id` is not allowed, e.g. origin not eligible.
410 GONE	TPID_EXISTENCE_ERROR	Account does not exist anymore.

Write API¶

Synch-ID

In case the Synch-ID should be included in the API responses (if preconditions are met), the APIs must be called with the respective accept header.

Without Synch-ID: application/vnd.netid.permission-center.netid-subject-status-v1+json
With Synch-ID: application/vnd.netid.permission-center.netid-subject-status-audit-v1+json

Write privacy status¶

Request (incl. Sync-ID)¶

POST https://einwilligen.netid.de/netid-permissions?q.tapp_id.eq=<TAPP_ID> HTTP/1.1
Content-Type: application/vnd.netid.permission-center.netid-permissions-v2+json
Accept: application/vnd.netid.permission-center.netid-subject-status-audit-v1+json
Cookie: tpid_sec=<JWT_TOKEN>
Origin: <ORIGIN>

{
  "idconsent": "VALID"|"INVALID",
  "iab_tc_string": "<TCSTRING>"
}

Response (incl. Sync-ID)¶

HTTP/1.1 201 Created
Location: https://einwilligungsspeicher.netid.de/netid-user-status?q.tapp_id.eq=<TAPP_ID>
Access-Control-Allow-Origin: <ORIGIN>
Access-Control-Allow-Credentials: true

{
  "subject_identifiers": {
     "tpid": "<TPID>"|null,
     "sync_id": "<SYNC_ID>"
  }
}

Request properties¶

item	description
IDCONSENT	Is indicating the status of the consent "IDCONSENT". VALID = Consent is given. INVALID = Consent is revoked
IAB_TC_STRING	TC String which should be stored/updated for this netID user for this respective netID partner (TAPP)

Response properties¶

item	description
tpid	Users netID identifier (`tpid`). Only returned if consent "idconsent" is VALID, the `tpid` is known (i.e. user is already authenticated on the device) and status "PERMISSIONS_FOUND". Otherwise null.
sync_id	Partner specific sync-id of the netID user.

Response behavior¶

HTTP status code	status_code	meaning
201 CREATED		Call successful
400 BAD REQUEST	NO_TPID	No tpid_sec cookie in request available.
400 BAD REQUEST	TOKEN_ERROR	Token in cookie is expired or invalid.
400 BAD REQUEST	NO_PERMISSIONS	Parameters are missing. At least one permission must be set.
400 BAD REQUEST	JSON_PARSE_ERROR	Invalid JSON body, parse error.
400 BAD REQUEST	NO_REQUEST_BODY	Required request body is missing.
400 BAD REQUEST	PERMISSION_PARAMETERS_ERROR	Syntactic or semantic error in a permission (e.g. invalid TC String)
403 FORBIDDEN	TAPP_NOT_ALLOWED	Missing parameters in request/Requesting TAPP isn't active/Origin not eligible
410 GONE	TPID_EXISTENCE_ERROR	Account does not exist anymore.