Register or refresh a device

Authorization

ApiKey

AuthorizationBearer <token>

An API key, sent as Authorization: Bearer carillon_sk_live_…. A secret key sends, reads traces and manages devices; a mobile key may only register its own device and report that device’s events.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

device_id?string

Previous registration ID. Token rotation requires the matching installation_secret.

Formatuuid

installation_secret?string

32 random bytes encoded as unpadded base64url, persisted by this installation. Never expose it in logs or analytics.

Match^[A-Za-z0-9_-]{43}$

token*string

The provider token, exactly as the device received it.

Length1 <= length <= 512

platform*string

Value in

"ios"
"android"

environment*string

APNs environment detected by the SDK from the app build. Selects the sandbox or production APNs endpoint.

Value in

"production"
"sandbox"

external_id?string

Your user identifier. Multiple devices can share the same external_id.

Length1 <= length <= 256

tags?

timezone_id?string

Lengthlength <= 64

locale?string

Lengthlength <= 35

app_version?string

Lengthlength <= 64

app_build?string

CFBundleVersion on iOS or versionCode on Android, encoded as a string.

Lengthlength <= 64

bundle_id?string

Bundle identifier on iOS or package name on Android.

Lengthlength <= 256

os_version?string

OS version reported by the device, stored without normalization.

Lengthlength <= 64

push_permission?string

OS notification permission. iOS supports all four values; Android reports allowed or denied.

Value in

"allowed"
"denied"
"provisional"
"undetermined"
null

sdk_version?string

Lengthlength <= 64

opted_in?boolean

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/v1/devices" \  -H "Content-Type: application/json" \  -d '{    "token": "string",    "platform": "ios",    "environment": "production"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "token": "string",  "platform": "ios",  "environment": "production",  "external_id": "string",  "tags": {    "property1": "string",    "property2": "string"  },  "timezone_id": "string",  "locale": "string",  "app_version": "string",  "app_build": "string",  "bundle_id": "string",  "os_version": "string",  "push_permission": "allowed",  "sdk_version": "string",  "opted_in": true,  "invalidated_at": "2019-08-24T14:15:22Z",  "invalidation_reason": "string",  "last_active_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Register or refresh a device

Authorization

Request Body

Response Body

200application/json

413application/problem+json

`application/json`

`application/problem+json`