Ephemeral Tokens

About Ephemeral Tokens

Ephemeral tokens have special properties that better match the SIP authentication use case including being scoped such that it can’t be used to interact with the API. For clarity, there are three types of ephemeral tokens:

  1. The account level token, which does not require the creation of a KAZOO device, but must be referenced specifically in the Callflow/Pivot nodes for routing calls.
  2. A SIP device token. To use this, you reference a SIP device id (device_type=sip) in the URL when generating an ephemeral token. This will ring the latest registration if the device, or the user associated with that device, is referenced in a callflow/pivot. Effectively this is consistent with using SIP credentials so it can only have one registration (AOR) for each device id. a. For example, when a user is added you can create a SIP device object and associate it with the user. Then, the client would use an ephemeral token created using that device id in the URL. When the user (or SIP device) is referenced in Callflows or Pivot, the latest client that registered using any valid ephemeral token associated with that device ID would ring. b. If multiple devices are either using the same SIP device token, or separate tokens created referencing the same SIP device, they would be replacing any exiting registrations (IE: the SIP device will only ever ring the latest registered device). c. Clients using this token will inherit the device settings of the SIP device id.
  3. A meta device token. To use this, you reference a meta device id (device_type=meta) in the URL when generating an ephemeral token. This will ring the latest registered client of each unique token if the device, or the user associated with that device, is referenced in a callflow/pivot. Effectively each unique token generated for that device id will have its own independent registration (AOR) and they will all simultaneously ring. a. For example, when a user is added you can create a meta device object and associate it with the user. Then the client would use an ephemeral token created using that device id in the URL. When the user (or meta device) is referenced in Callflows/Pivot, any client that last registered using a unique ephemeral token associated with that device id would ring. b. If multiple devices are using the same meta device token then they overwrite any previous registration for that token but if clients are using unique/separate tokens then when the meta device is referenced each active registration for each unique token is rung (IE: the meta device can ring one or more registrations so long as each is using a unique ephemeral token). c. Clients using this token will inherit the device settings of the meta device id.

Schema

Create

PUT /v2/accounts/{ACCOUNT_ID}/ephemeral_tokens

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ephemeral_tokens

Fetch

GET /v2/accounts/{ACCOUNT_ID}/ephemeral_tokens/{TOKEN}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ephemeral_tokens/{TOKEN}

On this page