Enrol a device with a one-time token and a certificate request

POST /d/v1/enroll

https://devices.tanba-ooh.kz/d/v1/enroll

Анықтамалықтың техникалық мәтіні ағылшын тілінде жазылған.

The first call of a player. An administrator issues an enrolment token in the console (valid 24 hours, single use). The player makes an ECDSA P-256 key, sends a certificate request for it together with the token, and receives its device certificate, valid for one year, and the chain up to the device certificate authority. From then on every call except this one and the reading of the revocation lists presents that certificate. The token is the only credential of this call, and the calls from one address are rate limited.

The device protocol is in beta: the object identifiers of the signed attributes of the approval envelope sit in a provisional test arc, 1.3.6.1.4.1.59999.1. A registered arc replaces it before the protocol is called stable.

Аутентификация

Ашық шақыру: сұраудың денесіндегі бір реттік тіркеу токені тұлғаны растайды.

Сұраудың денесі

`application/json`

Атауы	Түрі	Міндетті	Сипаттама	Мысал
`token`	string	иә	The one-time enrolment token from the console.	`"tdt_4f9c2a71b86e3d05"`
`csr`	string	иә	Certificate request for the device key, PEM or base64 of the DER form; ECDSA P-256.	`"MIIBEjCBuAIBADAZMRcwFQYDVQQDEw5leGFtcGxlLXBsYXllcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABA"`
`model`	string		Model of the player.	`"XP-100"`
`firmware`	string		Firmware version of the player.	`"4.2.1"`
`serial_no`	string		Serial number of the player.	`"XP100-0042"`
`spec_version`	string		Version of the conformance specification the player claims.	`"1.1"`

Мысал

{
  "token": "tdt_4f9c2a71b86e3d05",
  "csr": "MIIBEjCBuAIBADAZMRcwFQYDVQQDEw5leGFtcGxlLXBsYXllcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABA",
  "model": "XP-100",
  "firmware": "4.2.1",
  "serial_no": "XP100-0042",
  "spec_version": "1.1"
}

Жауаптар

200 The device is enrolled.

`application/json`

Атауы	Түрі	Міндетті	Сипаттама	Мысал
`device_id`	string (uuid)	иә	Identifier of the device; it is in the certificate.	`"5c0e8f3a-71d2-4b6e-9a14-d8e2f7b30c59"`
`certificate_pem`	string	иә	The device certificate in PEM form.	`"-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----\n"`
`chain_pem`	string	иә	The chain up to the device certificate authority in PEM form.	`"-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----\n"`
`nonce`	string	иә	The nonce for the first heartbeat.	`"3b9f0c6e2a7d41f85e0b9a3c7d2e1f60"`
`not_after`	string (date-time)	иә	When the certificate expires.	`"2027-10-14T09:00:00Z"`
`revocation_list`	object \| null		The newest revocation list: its version and address.
`revocation_list.version`	integer		Version of the list.	`42`
`revocation_list.url`	string		Address of the list.	`"https://devices.tanba-ooh.kz/d/v1/revocations/42"`

Мысал

{
  "device_id": "5c0e8f3a-71d2-4b6e-9a14-d8e2f7b30c59",
  "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----\n",
  "chain_pem": "-----BEGIN CERTIFICATE-----\nMIIB...\n-----END CERTIFICATE-----\n",
  "nonce": "3b9f0c6e2a7d41f85e0b9a3c7d2e1f60",
  "not_after": "2027-10-14T09:00:00Z",
  "revocation_list": {
    "version": 42,
    "url": "https://devices.tanba-ooh.kz/d/v1/revocations/42"
  }
}

Қателер

Қателер problem құжаты (application/problem+json) түрінде, тұрақты code өрісімен келеді.

Мәртебесі	Мағынасы
403	The token is unknown, used or expired (`invalid_token`).
422	Field errors (`validation_failed`).
429	Rate limit; see `Retry-After`.
503	The device channel is switched off (`device_channel_disabled`).
default	An error as a problem document.

Код мысалдары

curl

curl -X POST 'https://devices.tanba-ooh.kz/d/v1/enroll' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "tdt_4f9c2a71b86e3d05",
  "csr": "MIIBEjCBuAIBADAZMRcwFQYDVQQDEw5leGFtcGxlLXBsYXllcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABA",
  "model": "XP-100",
  "firmware": "4.2.1",
  "serial_no": "XP100-0042",
  "spec_version": "1.1"
}'

Python

import requests

response = requests.post(
    "https://devices.tanba-ooh.kz/d/v1/enroll",
    headers={
        "Content-Type": "application/json",
    },
    json={
        "token": "tdt_4f9c2a71b86e3d05",
        "csr": "MIIBEjCBuAIBADAZMRcwFQYDVQQDEw5leGFtcGxlLXBsYXllcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABA",
        "model": "XP-100",
        "firmware": "4.2.1",
        "serial_no": "XP100-0042",
        "spec_version": "1.1",
    },
)
print(response.status_code, response.text)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "token": "tdt_4f9c2a71b86e3d05",
  "csr": "MIIBEjCBuAIBADAZMRcwFQYDVQQDEw5leGFtcGxlLXBsYXllcjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABA",
  "model": "XP-100",
  "firmware": "4.2.1",
  "serial_no": "XP100-0042",
  "spec_version": "1.1"
}`)
	req, err := http.NewRequest("POST", "https://devices.tanba-ooh.kz/d/v1/enroll", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(data))
}