Skip to content

Token-based API

Description of the token based integration of the netID Permission Center by the CMP.

A netID Partner (TAPP) that sends a user through the Single Sign-On Flow can requests an access token (token) provided after the successful login, based on which a user can be authenticated at the netID Permission Center to enable read/write access for that specific users privacy status.

The server-based requests are secured via the access token. Calls of this type are blocked from the browser environments for security reasons (no Origin header is allowed!)

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 HTTP/1.1
Accept: application/vnd.netid.permission-center.netid-user-status-audit-v1+json
Authorization: Bearer <Access Token>

Response (incl. Sync-ID)

HTTP/1.1 200 OK
Content-Type: application/vnd.netid.permission-center.netid-user-status-audit-v1+json

{
  "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 of the netID user are returned.
200 OK PERMISSIONS_NOT_FOUND Call successful. netID user is authenticated. No permission (privacy status) found to the given tapp_id. No subject_identifiers returned.
400 BAD REQUEST NO_TOKEN No bearer token in request available. User could not be identified as netID user.
400 BAD REQUEST TOKEN_ERROR Token in bearer token is expired or invalid.
403 FORBIDDEN TAPP_NOT_ALLOWED TAPP tapp_id is not allowed.
410 GONE TPID_EXISTENCE_ERROR Account does not exist anymore.

Write 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-subject-status-v1+json
With Sync-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 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 
Authorization: Bearer <Access Token>
{
  "idconsent": "VALID"|"INVALID",
  "iab_tc_string": "<TCSTRING>"
}

Response (incl. Sync-ID)

HTTP/1.1 201 Created
Location: https://einwilligungsspeicher.netid.de/netid-permissions

{
  "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_TOKEN No bearer token in request available.
400 BAD REQUEST TOKEN_ERROR Token in bearer token 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.
403 FORBIDDEN TAPP_NOT_ALLOWED Missing parameters in request/Requesting TAPP isn't active.
410 GONE TPID_EXISTENCE_ERROR Account does not exist anymore.