Identities

What a person chose — display name, availability — and where to ring them.

Read an identity's settings

GET /v1/identities/{identity}

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.

Response 200 — The identity's settings.

Field	Type	Description
identity	string
displayName	string | null
availability	string	What the person chose. Presence is what the platform sees. One of available, away, dnd.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
updatedAt	string (date-time)

Errors

Status	Code
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

Set an identity's display name, availability and metadata

PUT /v1/identities/{identity}

A PUT is the whole record; a field it leaves out returns to its default.

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.

Request body application/json

Field	Type	Description
displayName?	string	At most 120 characters.
availability?	string	What the person chose. Presence is what the platform sees. One of available, away, dnd. Default "available".
metadata?	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.

Response 200 — The identity's settings.

Field	Type	Description
identity	string
displayName	string | null
availability	string	What the person chose. Presence is what the platform sees. One of available, away, dnd.
metadata	object	The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it.
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
413	payload_too_large
429	rate_limited
500	internal

---

An identity's registered installs, most recently registered first

GET /v1/identities/{identity}/devices

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.
limit?	query	integer	1–100. Default 20.
cursor?	query	string	The nextCursor of the previous page. 1–512 characters.

Response 200 — A page of devices.

Field	Type	Description
data	Device[]
nextCursor	string | null	The cursor for the next page; null on the last.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
429	rate_limited
500	internal

---

Register or refresh one install

PUT /v1/identities/{identity}/devices/{deviceId}

A PUT is the whole registration: a field it leaves out is cleared. A push or VoIP token moves to the install that registered it last.

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.
deviceId	path	string	The tenant's own handle for the install. 1–200 characters.

Request body application/json

Field	Type	Description
platform	string	One of web, android, ios.
pushProvider?	string	One of fcm, apns_voip, web_push, none. Default "none".
pushToken?	string	1–4096 characters.
voipToken?	string	iOS PushKit; not the APNs alert token. 1–4096 characters.
sdkVersion?	string	At most 40 characters.
appVersion?	string	At most 40 characters.
osVersion?	string	At most 60 characters.
model?	string	At most 80 characters.

Response 200 — The device.

Field	Type	Description
identity	string
deviceId	string	The tenant's own handle for the install.
platform	string	One of web, android, ios.
pushProvider	string	One of fcm, apns_voip, web_push, none.
pushToken	string | null
voipToken	string | null	iOS PushKit; not the APNs alert token.
sdkVersion	string | null
appVersion	string | null
osVersion	string | null
model	string | null
lastSeenAt	string (date-time)
createdAt	string (date-time)
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
413	payload_too_large
429	rate_limited
500	internal

---

Remove one install, on logout

DELETE /v1/identities/{identity}/devices/{deviceId}

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.
deviceId	path	string	The tenant's own handle for the install. 1–200 characters.

Response 204 — Removed.

Errors

Status	Code
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal