User tags

User tags belong to an external_id within one app and one live/test mode. For example, update a user's subscription once and target all their devices by it. Device tags remain separate and are updated with SDK setTags().

Create or update tags

Use a secret API key with users:write. New secret keys include users:read, users:write and users:delete. Existing active keys with the full server scope set receive these permissions automatically at deployment; no key rotation is needed. Restricted keys retain their explicit permissions. Mobile keys cannot read or modify user tags.

curl -X PATCH 'https://api.carillon.dev/v1/users/customer-42/tags' \
  -H "Authorization: Bearer $CARILLON_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"tags":{"plan":"pro","trial":null}}'

The response is 200 with {"external_id":"customer-42","tags":{"plan":"pro"}} for a new profile. Existing keys are preserved; supplied keys are merged and null removes a key. An empty map changes nothing. The final map supports up to 50 keys and 4096 UTF-8 JSON bytes. Keys are 1–64 characters; values are strings (up to 256 characters), numbers or booleans. Updates exceeding the limits return 400 without changing the profile. Concurrent updates to different keys are preserved; for the same key the last applied update wins.

URL-encode the external ID in the path. It must contain 1–256 characters. The key determines the app and mode; neither comes from the request body. A profile may be created before any device exists, and remains when all devices detach.

Link devices and target an audience

Call SDK identify("customer-42") on each signed-in device. A device resolves user tags from its current external ID; tags are never copied into its own map. clearIdentity() detaches the device. Identifying a different user selects that user's tags.

Create a saved audience with this definition, then send to its audience ID:

{
  "name": "Pro iOS users",
  "definition": {
    "filters": [
      { "field": "user_tag", "key": "plan", "value": "pro" },
      { "field": "platform", "value": "ios" }
    ]
  }
}

The preview counts matching devices, not unique users. Recipients use the profile's current tags when the audience resolves. See audience filters. Test campaigns can simulate live devices too: each device uses the profile in its own mode, so test tags never override a live device's user tags.

Read or delete a profile

GET /v1/users/{externalId}/tags requires users:read and returns the same response shape. A missing profile returns 404.

DELETE /v1/users/{externalId}/tags requires users:delete and returns 204, including when already absent. It deletes only the profile: devices, external IDs and device tags remain unchanged. A later PATCH can recreate it and existing devices will use it again. Profiles without devices are not automatically removed. Deleting the app or erasing its organization deletes its profiles as well.