Whitelistings

A whitelisting admits one device to the network of a Sign-In Context by its MAC address, without a sign-in flow. See Whitelist for the module in the Admin Dashboard.

Base path: {apiBaseUrl}/organizations/{organizationId}/contexts/sign-in/{contextId}/whitelistings

Operations

Operation	Method and path	Permission
List active whitelistings	GET .../whitelistings	Sign In › Sign In Modules › Whitelisting (Read)
Get a whitelisting	GET .../whitelistings/{whitelistingId}	Sign In › Sign In Modules › Whitelisting (Read)
Create a whitelisting	POST .../whitelistings	Sign In › Sign In Modules › Whitelisting (Write)
Update a whitelisting	PUT .../whitelistings/{whitelistingId}	Sign In › Sign In Modules › Whitelisting (Write)
Create whitelistings in a batch	POST .../whitelistings/batch-create	Sign In › Sign In Modules › Whitelisting (Write)
End whitelistings in a batch	POST .../whitelistings/batch-revoke	Sign In › Sign In Modules › Whitelisting (Write)

The permission is set per Sign-In Context, and its ID in requiredPermission is sign-in.whitelistings. See API permissions.

The whitelisting object

Field	Type	Description
whitelistingId	string	The ID of the whitelisting. Use it to read or update the whitelisting.
mac	string	The MAC address of the device, in lower case.
name	string or null	A name that describes the device. null for a whitelisting created without a 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 it has no end date.

Validation rules

• MAC address: aa:bb:cc:dd:ee:ff, six pairs of hexadecimal digits separated by colons, in upper or lower case. It is stored and returned in lower case. Dashes are not accepted.
• Name: required, 2 to 100 characters.
• Description: up to 200 characters.
• Tags: up to 50 tags, each 2 to 30 characters. They are stored in lower case.
• Characters in the name, the description and the tags: letters of any alphabet, including accented letters, digits, space and _ : ( ) & , . / " + -.
• End date (validUntil): a date, YYYY-MM-DD. It is the last day the whitelisting is valid: the whitelisting ends at the end of that day in the time zone of the platform, and expiresAt shows the exact moment. Leave it out for a whitelisting that does not expire. The date must be today or later, and before 2099-12-31. A later date returns 400 with VALIDATION_FAILED and an entry in errors for validUntil with the code OUT_OF_RANGE and the detail Must be before 2099-12-31.
• Batches: 1 to 500 items per request, each device once. Upper and lower case count as the same MAC address.

Active and ended whitelistings

A whitelisting is active until its expiresAt, or until it is revoked, for example by a batch revoke. After that it has ended:

• A device has at most one active whitelisting in a context. To whitelist a device again after its whitelisting has ended, create a new one.
• An ended whitelisting cannot be changed. An update returns 409 with the errorCode SIGN_IN_WHITELISTING_ENDED.
• The list of active whitelistings shows only whitelistings that have not ended. Get a whitelisting returns a whitelisting whether it is active or has ended.

Errors are in Errors, pagination in Pagination. The legacy operations with the x-auth-token header are in Whitelisting (legacy).