Initialization

Encedo HEM needs to be initialized before it's usable. This process is called Personalization and these two API endpoints are dedicated for this operation.

These two endpoints are wide open and do not need any authorization data. After the successful personalization of the device, future calls will raise Error 406.

The format of the initialization data is described in "General information".

Personalization

Phase 1 - challenge

Get challenge data

GET https://my.ence.do/api/auth/init

Get initial data (challenge) as the first step in the personalization process.

200: OK Operation sucessful

{
  "exp": 1647936471,
  "spk": "dONxxYB9mq9C3UjrVCgkAw6O30JqZkFprT55fq3ZfAM=",
  "jti": "m4M5Yn6HNoyABv+W1JiIQtSP4xiq6PBD1x5b2/PlJl8=",
  "genuine": "LH8nwNPgH3PV+zfry/Savrso/Q4=.MTY0NzkzNjQ3MQ==.MEYCIQD0GFLsc0JGDo5QoWY1m/Jcw7FKpe5kPoaRop6EWvBfhQIhALMA3DwwigtCTIL5Sopa38aWZUL4AGYUVq3u1v6f2Pjn",
  "eid": "lvVc8WGbc8m95VvUVgZO7Z1maYOPdX8Pn0cveNPtYyA="
}

403: Forbidden Clock RTC not set

409: Conflict Incorrect internal state

406: Not Acceptable Operation failed

Response data for successful operation

Name	Type	Description
eid	String	EncedoID, public key of the instance
exp	String	Expire timestamp
genuine	String	Attestation data
jti	String	Token id
spk	String	Session public key

Phase 2 - response

Upload initial configuration

POST https://my.ence.do/api/auth/init

Upload a well formated initial configuration signed by user passphrase.

Headers

Name	Type	Description
Content-Type*	String	application/json

Request Body

Name	Type	Description
init*	String	Initialization structure

200: OK Operation sucessful

{
  "instanceid": "e7aafede-76b1-c7c8-784b-c963967fe307",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzY29wZSI6InN5c3RlbTpjb25maWciLCJzdWIiOiJVIiwiaWF0IjoxNjQ3OTM2NDE2LCJleHAiOjE2NDc5NjUyMTYsImp0aSI6Im9JTTVZbElqYXYwRUdqQlpxVDdtbDZ3Q0d4WTRYcmpGR0lweWd6Q1lEbWM9In0.aAW7qaAjbD9y36VI0XVtO-f8l2kV0T4Y4kZZxpaAPEg",
  "genuine": "LH8nwNPgH3PV+zfry/Savrso/Q4=.MTY0NzkzNjQ3Ng==.MEQCIHJ2fARkMLCM3bb8wBImJWQMgCOCnt+x8idort0IVnP+AiA4hSYO3hV6K8/vZKAiAyiJxYMQyxHQo5qP1P2AEqEiRw=="
}

403: Forbidden Clock RTC not set

406: Not Acceptable Operation failed

409: Conflict Incorrect internal state

400: Bad Request Incorrect argument(s)

401: Unauthorized Initialization structure validation failed

Response data for successful operation

Name	Type	Description
genuine	String	Attestation data
instanceid	String	Instance unique ID
token	String	JWT access token (refered as JWT_TOKEN)

Log entries (directly and indirectly as indicated)

Event	Result	Source
LOG_TYPE_DEVICE_INITED	LOG_RESULT_OK	200
LOG_TYPE_STARTUP	LOG_RESULT_OK	On every powerup as second log entry (the first is LOG_TYPE_KEY_INIT)