Configuration
These operations allow the read and update of the device configuration. This section includes Secure Enclave provisioning (on Encedo PPA only and during manufacture only).
Manage device configuration
Allowed only to call Get configuration.
Get configuration
https://my.ence.do/api/system/configRead the device configuration data.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer JWT_TOKEN |
Response status code
- 200: Operation successful
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 412: Protocol error - CORS validation failed
- 500: Internal server error
{
"iat": 1647381403,
"uts": 1647381403,
"devid": "2023b758c209269a",
"instanceid": "f4980240-da72-13e3-f45c-2ffbde2a1800",
"eid": "ff6/rpgprw6OjcPbedIB5LbsxjZqmnf43J1zeK1x82I=",
"eid_sign": "T61jY1AgV5XUW++eAcQibRDFOl5KjKwLGdo+U0def8A=",
"user": "John Doe",
"email": "john@example.com",
"hostname": "example.ence.do",
"dnsd": true,
"trusted_ts": true,
"trusted_backend": true,
"allow_keysearch": true,
"origin": "*",
"ctx": 0,
"http_option_hsts": true,
"http_option_dosprot_mode": 1,
"ip": "192.168.11.1/24",
"genuine_id": "0123eb561f5ea073ee",
"storage_mode": 81,
"storage_disk0size": 8388607,
"storage_capacity": 120979451,
"spk": "fi2bgSQwaGhLkRi016q9saqeTWvrLyU08nM8hJUpTBg=",
"nonce": "fOw1YvMYWIqbTfrxgQFzEuvcJozIRqEVKluO9KDza0w="
}
No response body.
No response body.
No response body.
No response body.
Response data for successful operation
| Value | Type | Description |
|---|---|---|
allow_keysearch | Bool | True if an allowed search for a key without authentication. |
ctx | Number | Instance context id. |
devid | String | Device unique ID. |
dnsd | string | True if build-in DNS server is enabled. |
eid | String | EncedoID, public key of the instance. |
eid_sign | String | Audit log signing public key. |
email | String | Email address. |
genuine_id | String | Secure Enclave serial number (on Encedo PPA only). |
http_option_dosprot_mode | Number | Timeout (disabled if 0) to finish the HTTP request in 0.5sec multipliers. |
http_option_hsts | Bool | True enable HSTS HTTP security headers. |
hostname | String | Hostname, domain name associated with this device. |
iat | Number | Current timestamp. |
instanceid | String | Instance unique ID |
ip | String | IP address associated with this device. |
nonce | String | Random nonce. |
origin | String | CORS allowed origins. |
spk | String | Session public key. |
storage_capacity | Number | Capacity (in sectors) of embedded microSD card (on Encedo PPA only). |
storage_disk0size | Number | Capacity (in sectors) of regular Disk 0 (on Encedo PPA only). |
storage_mode | Number | Dsks 0 default mode and encryption mode of Disk 1 (on Encedo PPA only). |
trusted_backend | Bool | True is backend is trusted and can control this instance. |
trusted_ts | Bool | True is backend is a trusted time source. |
user | String | Username, display name. |
uts | Number | Last RTC update timestamp. |
Update configuration
https://my.ence.do/api/system/configChange some configuration data, e.g. options, password or update TLS certificate.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer JWT_TOKEN |
| Content-Type* | String | application/json |
Request Body
| Name | Type | Description |
|---|---|---|
allow_keysearch | Bool | True if an allowed search for a key without authentication. |
email | String | Contact email address |
storage_mode | Number | Disk0 default mode and Disk1 encryption mode (on Encedo PPA only) |
wipeout | Bool | True to wipe out the device (reset to factory default). |
origin | String | CORS access control data |
trusted_ts | Bool | True is backend is a trusted time source. |
trusted_backend | Bool | True is backend is trusted and can control this instance. |
tls | String | TLS x509 certificate data (check below) |
user | String | Username |
userkey | String | New password public key |
userkey_nonce | String | New password authentication nonce |
userkey_hmac | String | New password authentication code |
ctx | Number | Instance context id. |
dnsd | Bool | True to enable DNS server |
storage_disk0size | Number | Disk0 size in sectors (on Encedo PPA only) |
gen_csr | Bool | True if requesting CSR generation |
http_option_hsts | Bool | True enable HSTS HTTP security headers |
http_option_dosprot_mode | Number | Timeout (disabled if 0) to finish the HTTP request in 0.5sec multipliers |
Members of the tls object
| Name | Type | Description |
|---|---|---|
emp | String | (optional) Ephemeral public key (transport key) |
key | String | (optional) Encrypted private key |
crt | String | Base64 encoded DER x509 certificate |
Response status code
- 200: Operation successful
- 400: Incorrect argument(s)
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 406: Operation failed
- 409: Incorrect internal state
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 500: Internal server error
{
"csr": "MIICATCCAaagAwIBAgIBbTAKBggqhkjOPQQDAjBCMQswCQYDVQQGEwJVSzEXMBUGA1UECgwORW5jZWRvIExpbWl0ZWQxGjAYBgNVBAMMEUVuY2VkbyBDdXN0b2R5IENBMB4XDTIwMTAwNTE5MjkzM1oXDTIzMTAwNTE5MjkzM1owQDELMAkGA1UEBhMCVUsxEzARBgNVBAoMCkVuY2VkbyBMdGQxHDAaBgNVBAMMEyMwMTIzZWI1NjFmNWVhMDczZWUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASdUuVLRdTcTd1DSu/6qTdh562q5WsXGEcHBP/gpUvHcU/501HwR2NybMmFQQ7/HgLgCYgaTPE+kvq6Lb0AuRf/o4GOMIGLMA4GA1UdDwEB/wQEAwIHgDAJBgNVHRMEAjAAMB0GA1UdDgQWBBSqAknAzbCHMuji+7pJhSslHyuApTAfBgNVHSMEGDAWgBR5VVeOla0ntTsGycLKHAI2qA58BjAuBgNVHREEJzAloCMGCSsGAQQBg7cnAaAWBBRGRaJpZ1sXy+HKN/vFyusw810N+DAKBggqhkjOPQQDAgNJADBGAiEA7un6HD6upjiPmhCLYMCk3fxNZyx6cZMNWzQV7LozMTMCIQDptL4bvTeMymy5WiGKrFPkDv7f+Nz9x5vop9vZry0N1Q==",
"genuine": "qgJJwM2whzLo4vu6SYUrJR8rgKU=.MTY0NzY0MTI4NQ==.MEYCIQCYDC9IDlnGlkBI7/1YPMSIC/31nfiFUISpWEb3Pw5vAgIhAPIcyOufL4MQPwl/dUpM4W8gi+IECx9i9m1LcSHo8Bqo",
"updated": true,
"reboot_required": true
}
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
Response data for successful operation
| Name | Type | Description |
|---|---|---|
csr | String | Requested x509 CSR, base64 encoded DER file. |
genuine | String | Attestation data. |
reboot_required | Bool | True if a reboot is required for changes to take effect. |
updated | Bool | True is configuration have been changed. |
Log entries
| Event | Result | Source |
|---|---|---|
| LOG_TYPE_FAILED_SCOPE_CHECK | LOG_RESULT_FAILED | 403 |
| LOG_TYPE_CONFIG_UPDATED | LOG_RESULT_OK | 200 |
| LOG_TYPE_CONFIG_UPDATED | LOG_RESULT_FAILED | 406 |
Get device attestation data
This endpoint is available only on Encedo PPA.
This endpoint is ignoring access scope, effectively any scope value is allowed as long as the JWT_TOKEN is valid.
The Authorization header is not required on fresh, not personalised devices.
Device attestation
https://my.ence.do/api/system/config/attestationObtain device attestation data, which serves as proof of genuineness.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization | String | Bearer JWT_TOKEN |
Response status code
- 200: Operation successful
- 401: Missing or invalid JWT_TOKEN
- 409: Incorrect internal state
- 412: Protocol error - CORS validation failed
- 500: Internal server error
{
"crt": "MIICATCCAaagAwIBAgIBbTAKBggqhkjOPQQDAjBCMQswCQYDVQQGEwJVSzEXMBUGA1UECgwORW5jZWRvIExpbWl0ZWQxGjAYBgNVBAMMEUVuY2VkbyBDdXN0b2R5IENBMB4XDTIwMTAwNTE5MjkzM1oXDTIzMTAwNTE5MjkzM1owQDELMAkGA1UEBhMCVUsxEzARBgNVBAoMCkVuY2VkbyBMdGQxHDAaBgNVBAMMEyMwMTIzZWI1NjFmNWVhMDczZWUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASdUuVLRdTcTd1DSu/6qTdh562q5WsXGEcHBP/gpUvHcU/501HwR2NybMmFQQ7/HgLgCYgaTPE+kvq6Lb0AuRf/o4GOMIGLMA4GA1UdDwEB/wQEAwIHgDAJBgNVHRMEAjAAMB0GA1UdDgQWBBSqAknAzbCHMuji+7pJhSslHyuApTAfBgNVHSMEGDAWgBR5VVeOla0ntTsGycLKHAI2qA58BjAuBgNVHREEJzAloCMGCSsGAQQBg7cnAaAWBBRGRaJpZ1sXy+HKN/vFyusw810N+DAKBggqhkjOPQQDAgNJADBGAiEA7un6HD6upjiPmhCLYMCk3fxNZyx6cZMNWzQV7LozMTMCIQDptL4bvTeMymy5WiGKrFPkDv7f+Nz9x5vop9vZry0N1Q==",
"genuine": "qgJJwM2whzLo4vu6SYUrJR8rgKU=.MTY0NzY0MTI4NQ==.MEYCIQCYDC9IDlnGlkBI7/1YPMSIC/31nfiFUISpWEb3Pw5vAgIhAPIcyOufL4MQPwl/dUpM4W8gi+IECx9i9m1LcSHo8Bqo"
}
No response body.
No response body.
No response body.
No response body.
Response data for successful operation
| Name | Type | Description |
|---|---|---|
crt | String | Base64 encoded DER x509 device certificate. |
genuine | String | Attestation data. |
Factory provisioning
This endpoint is available only on Encedo PPA.
This endpoint is used during the manufacturing process to provision the Secure Enclave chip. After successful provisioning, all following calls to this endpoint will return a response code 406.
Factory provisioning
https://my.ence.do/api/system/config/provisioningOn factory Secure Enclave provisioning (on Encedo PPA only).
Headers
| Name | Type | Description |
|---|---|---|
| Content-Type* | String | application/json |
Request Body
| Name | Type | Description |
|---|---|---|
crt* | String | x509 certificate |
genuine* | String | Attestation data |
Response status code
- 200: Operation successful
- 400: Incorrect or malformated argument(s)
- 403: Device personalized
- 406: Operation failed
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 500: Internal server error
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.