Create a whitelisting

POST /organizations/{organizationId}/contexts/sign-in/{contextId}/whitelistings

Permission: Sign In › Sign In Modules › Whitelisting (Write). See API permissions.

The device must not already have an active whitelisting in the context. A device that has one returns 409 with the errorCode ALREADY_EXISTS and nothing is created, so repeating the call is safe. Update that whitelisting instead, or use Create whitelistings in a batch, which updates it.

Request

Parameter	In	Type	Required	Description
organizationId	Path	string	Yes	The Organization ID of the API key. Any other ID returns 404.
contextId	Path	string	Yes	The ID of a Sign-In Context of the Organization. Any other ID returns 404.
mac	Body	string	Yes	The MAC address of the device, aa:bb:cc:dd:ee:ff, in upper or lower case.
name	Body	string	Yes	A name that describes the device, 2 to 100 characters.
description	Body	string	No	The description, up to 200 characters.
tags	Body	string[]	No	Up to 50 tags, each 2 to 30 characters. Stored in lower case.
validUntil	Body	string (date)	No	The last day the whitelisting is valid, YYYY-MM-DD, today or later and before 2099-12-31. It ends at the end of that day in the time zone of the platform. Left out, the whitelisting does not expire.

The name, the description and the tags accept letters, digits, space and _ : ( ) & , . / " + -. See Validation rules.

Request example

cURL

curl -X POST "$API_BASE_URL/organizations/$ORGANIZATION_ID/contexts/sign-in/$CONTEXT_ID/whitelistings" \
  -H "Authorization: Bearer $NCP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mac": "02:00:5E:10:AB:01",
    "name": "Lobby display",
    "description": "Digital signage, main entrance",
    "tags": ["Signage", "lobby"],
    "validUntil": "2026-12-31"
  }'

Response

201 with the new whitelisting. The Location header is the path of Get a whitelisting for it.

Field	Type	Description
whitelistingId	string	The ID of the whitelisting.
mac	string	The MAC address, in lower case.
name	string	The name.
description	string or null	The description, or null when there is none.
tags	string[]	The tags, in lower case, in no particular order.
createdAt	string (date-time)	When the whitelisting was created.
expiresAt	string (date-time) or null	When the whitelisting ends. null when validUntil was left out.

Response example

201

{
  "whitelistingId": "6aba6cb007a2eda4c7c79ade",
  "mac": "02:00:5e:10:ab:01",
  "name": "Lobby display",
  "description": "Digital signage, main entrance",
  "tags": ["lobby", "signage"],
  "createdAt": "2026-09-28T13:33:36.341Z",
  "expiresAt": "2026-12-31T22:59:59.999Z"
}

In this example expiresAt is the last millisecond of 31 December in the time zone of the platform, written in UTC.

Errors

Status	errorCode	When
400	VALIDATION_FAILED	A field is missing or breaks a validation rule. errors names each field, for example mac with the code INVALID_FORMAT, or validUntil with the code OUT_OF_RANGE when it is before today or not before 2099-12-31. Nothing is created.
404	RESOURCE_NOT_FOUND	organizationId is not the Organization of the API key, or contextId is not one of its Sign-In Contexts.
409	ALREADY_EXISTS	The device already has an active whitelisting: The device already has an active whitelisting in this context, so nothing was created. Update that whitelisting instead, or use the batch create, which updates it.
409	SIGN_IN_WHITELISTING_REFUSED	The rules for whitelistings of the context refuse the device: The context refused the whitelisting. Nothing is created.

Errors common to all operations are in Errors.