Migrate from the legacy API

Mapping from the legacy Sign In API to the Sign In API. Both APIs are available. A Legacy API key does not work with the Sign In API, and an API key from the Applications page does not work with the legacy API.

Bases

API	Base
Legacy API	https://<API host>/v1/org/{organizationId}/contexts/sign-in/{contextId}
Sign In API	https://<API host>/api/v2/organizations/{organizationId}/contexts/sign-in/{contextId}

Both are served from the same API host. The API base URL on the Applications page ends in /api/v2; the legacy paths start right after the host.

Operations

Paths are relative to the bases above.

Operation	Legacy API	Sign In API
Create a whitelisting	POST .../modules/whitelistings	POST .../whitelistings
Update a whitelisting	PUT .../modules/whitelistings	PUT .../whitelistings/{whitelistingId}
Create whitelistings in a batch	POST .../modules/whitelistings/batch/add	POST .../whitelistings/batch-create
End whitelistings in a batch	POST .../modules/whitelistings/batch/remove	POST .../whitelistings/batch-revoke
List active whitelistings	GET .../modules/whitelistings/active	GET .../whitelistings
Add email patterns	POST .../policies/{accessPolicyId}/emails	POST .../access-policies/{policyId}/email-patterns/add
Remove email patterns	DELETE .../policies/{accessPolicyId}/emails	POST .../access-policies/{policyId}/email-patterns/remove

The Sign In API also lists, reads, creates, updates and deletes access policies. The legacy API changes only their email patterns.

Differences

• Authentication. Authorization: Bearer <token> instead of the x-auth-token header.
• API key scope. A Legacy API key belongs to one Sign-In Context. An API key from the Applications page belongs to the Organization and holds separate API permissions in each Sign-In Context.
• IP access list. Each API key has its own IP access list. The Admin Dashboard Access list in Organization Settings no longer decides which addresses can call the API. While it is limited to specific networks, Require IP access list stays on.
• Errors. Every error is application/problem+json with a stable errorCode; see Errors.
• The policy is named by its ID. The Sign In API names the access policy by its policyId in the path, and default is not accepted. Find the ID with List access policies.
• Pagination. The list of active whitelistings is paginated with limit and cursor and returns whole whitelistings instead of MAC addresses; see Pagination.
• Batches. A batch returns one result per item, in the order sent, with an outcome for each, instead of lists of MAC addresses or patterns. An item listed twice returns 400.
• Resource IDs in the path. A whitelisting is updated by its whitelistingId in the path, not by a field in the body.
• Created objects. Creating a whitelisting returns 201 with the new whitelisting and a Location header with its path.
• No end date. A whitelisting without an end date has expiresAt null.
• MAC addresses. aa:bb:cc:dd:ee:ff only, in upper or lower case. Dashes are not accepted.
• Revoking access. When email patterns are removed, revokeAccess defaults to false. The legacy revokeUserEngagement defaulted to true.

Fields

Operation	Legacy field	Sign In API field
Create or update a whitelisting	toDate	validUntil. Unchanged meaning: valid through the end of that day.
Create or update a whitelisting	tags[].value	tags[], plain strings
Create a whitelisting	id in the body	Not sent. The response carries the new whitelistingId.
Update a whitelisting	id in the body	whitelistingId in the path
Update a whitelisting	mac in the body	Not sent. The whitelisting keeps its device.
Create whitelistings in a batch	autoGenerateTags	tagsFromDescription
Create whitelistings in a batch	autoGenerateDateTag	batchTimeTag
Create whitelistings in a batch	createdWhitelistingMacs	results[] entries with the outcome CREATED
Create whitelistings in a batch	existingWhitelistingMacs	results[] entries with the outcome UPDATED
Create whitelistings in a batch	faultyRequests, the refused entries	results[] entries with the outcome REJECTED and a reason
Create whitelistings in a batch	updatedLogins	Not returned
End whitelistings in a batch	macs[], objects with a mac field	macs[], plain strings
End whitelistings in a batch	nrOfWhitelistingsInRevokeRequest	Not returned. results[] has one entry per device.
End whitelistings in a batch	nrOfWhitelistingsThatHadActiveLoginsThatWereRevoked	Not returned. results[] entries with the outcome ENDED are the whitelistings that were ended.
List active whitelistings	An array of MAC addresses	items[], whole whitelistings, one page at a time
Add email patterns	emails	emailPatterns
Add email patterns	Response policyEmails	Response emailPatterns
Add email patterns	Response warnings[], with email and reason	Response results[], one entry per pattern with the outcome ADDED, ALREADY_IN_POLICY or IN_OTHER_POLICY
Remove email patterns	emails	emailPatterns
Remove email patterns	revokeUserEngagement, default true	revokeAccess, default false
Remove email patterns	Response policyEmails	Response emailPatterns
Remove email patterns	Response removedEmails[].email	results[].emailPattern, with the outcome REMOVED or NOT_IN_POLICY
Remove email patterns	removedEmails[].revokedLoginsForSelfProvisioning	results[].revoked.selfProvisioningLogins
Remove email patterns	removedEmails[].revokedLoginsForMeetingHost	results[].revoked.meetingHostLogins
Remove email patterns	removedEmails[].revokedWhitelisting	results[].revoked.whitelistings
Remove email patterns	removedEmails[].revokeLoginsforConferences	Not returned