Accessing and modifying per-device data

Overview

After you use the DCDevice class to generate an ephemeral token that identifies a device, your server uses HTTP POST commands to send requests to the query and update endpoints. The HTTP header field in each request must contain the authentication key you receive from Apple in a JSON web token (JWT). To create this token, you can use the same steps you use to create a provider authentication token for Apple Push Notification service (APNs); for details, see Communicate with APNs using authentication tokens.

Create the payload for a query request

To query the bits, you create a JSON payload that contains the fields listed in the table below.

Here’s an example of a payload included in a query request:

{
   "device_token" : "wlkCDA2Hy/CfrMqVAShs1BAR/0sAiuRIUm5jQg0a..."
   "transaction_id" : "5b737ca6-a4c7-488e-b928-8452960c4be9",
   "timestamp" : 1487716472000 
}

When your query request succeeds, you receive a response that contains the fields listed in the table below.

Create the payload for an update request

To update the bits, you create a JSON payload that contains the fields listed in the table below.

Here’s an example of a payload included in an update request:

{
   "device_token" : "wlkCDA2Hy/CfrMqVAShs1BAR/0sAiuRIUm5jQg0a..."
   "transaction_id" : "5b737ca6-a4c7-488e-b928-8452960c4be9",
   "timestamp" : 1487716472000,
   "bit0" : true,
   "bit1" : false 
}

If the update was successful, you receive the HTTP response code 200. For a full list of the response codes you can receive, see Understand the HTTP response codes.

Create the payload for a device validation request

To validate a device, you create a JSON payload that contains the fields listed in the table below.

Here’s an example of a payload included in a device-validation request:

{
   "device_token" : "wlkCDA2Hy/CfMqVAShslBAR/0sAiuRIUm5jQg0aJJ2gZl1cs..." 
   "transaction_id" : "5b737ca6-a4c7-488e-b928-8452960c4be9",
   "timestamp" : 1487716472000 
} 

If the request was successful, you receive the HTTP response code 200. For a full list of response codes you can receive, see Understand the HTTP response codes.

Send the request

Each request you send to the query and update endpoints must include an authorization header that contains your authentication key. The authentication key must use the ES256 algorithm and be in the Base 64 URL–encoded JSON web token format. If your token doesn’t use this format, you receive a BAD_AUTHENTICATION_TOKEN HTTP error.

In the curl command you create to send a request, you specify the authorization header and include your authentication key using Bearer \, like this:

-H "``Authorization: Bearer <GeneratedJWT>``" \

To send a query request, your curl command might look similar to the one shown here:

curl -i --verbose -H "Authorization: Bearer <GeneratedJWT>" \ -X POST --data-binary @ValidQueryRequest.json \ 
https://api.development.devicecheck.apple.com/v1/query_two_bits 

To send an update request, your curl command might look similar to the one shown here:

curl -i --verbose -H "Authorization: Bearer <GeneratedJWT>" \ -X POST --data-binary @ValidUpdateRequest.json \ https://api.development.devicecheck.apple.com/v1/update_two_bits 

To send a device-validation request, your curl command might look similar to the one shown here:

curl -i --verbose -H "Authorization: Bearer <GeneratedJWT>" \ -X POST --data-binary @ValidValidateDeviceToken Request.json \ https://api.development.devicecheck.apple.com/v1/validate_device_token 

Understand the HTTP response codes

When you use the query and update endpoints to communicate with the server, you may receive one of the response codes listed in the table below.

See Also

Device identification

• DCDevice