Skip to main content

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 usersUser✓Master✓ExtAuthAllowed only to call Get configuration.

Allowed only to call Get configuration.

Get configuration​

GEThttps://my.ence.do/api/system/config
Required access scopesystem:configalternative:auth:ext:pairlogger:get

Read the device configuration data.

Headers​

NameTypeDescription
Authorization*StringBearer JWT_TOKEN

Response status code​

{
"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="
}

Response data for successful operation​

ValueTypeDescription
allow_keysearchBoolTrue if an allowed search for a key without authentication.
ctxNumberInstance context id.
devidStringDevice unique ID.
dnsdstringTrue if build-in DNS server is enabled.
eidStringEncedoID, public key of the instance.
eid_signStringAudit log signing public key.
emailStringEmail address.
genuine_idStringSecure Enclave serial number (on Encedo PPA only).
http_option_dosprot_modeNumberTimeout (disabled if 0) to finish the HTTP request in 0.5sec multipliers.
http_option_hstsBoolTrue enable HSTS HTTP security headers.
hostnameStringHostname, domain name associated with this device.
iatNumberCurrent timestamp.
instanceidStringInstance unique ID
ipStringIP address associated with this device.
nonceStringRandom nonce.
originStringCORS allowed origins.
spkStringSession public key.
storage_capacityNumberCapacity (in sectors) of embedded microSD card (on Encedo PPA only).
storage_disk0sizeNumberCapacity (in sectors) of regular Disk 0 (on Encedo PPA only).
storage_modeNumberDsks 0 default mode and encryption mode of Disk 1 (on Encedo PPA only).
trusted_backendBoolTrue is backend is trusted and can control this instance.
trusted_tsBoolTrue is backend is a trusted time source.
userStringUsername, display name.
utsNumberLast RTC update timestamp.

Update configuration​

POSThttps://my.ence.do/api/system/config
Required access scopesystem:config

Change some configuration data, e.g. options, password or update TLS certificate.

Headers​

NameTypeDescription
Authorization*StringBearer JWT_TOKEN
Content-Type*Stringapplication/json

Request Body​

NameTypeDescription
allow_keysearchBoolTrue if an allowed search for a key without authentication.
emailStringContact email address
storage_modeNumberDisk0 default mode and Disk1 encryption mode (on Encedo PPA only)
wipeoutBoolTrue to wipe out the device (reset to factory default).
originStringCORS access control data
trusted_tsBoolTrue is backend is a trusted time source.
trusted_backendBoolTrue is backend is trusted and can control this instance.
tlsStringTLS x509 certificate data (check below)
userStringUsername
userkeyStringNew password public key
userkey_nonceStringNew password authentication nonce
userkey_hmacStringNew password authentication code
ctxNumberInstance context id.
dnsdBoolTrue to enable DNS server
storage_disk0sizeNumberDisk0 size in sectors (on Encedo PPA only)
gen_csrBoolTrue if requesting CSR generation
http_option_hstsBoolTrue enable HSTS HTTP security headers
http_option_dosprot_modeNumberTimeout (disabled if 0) to finish the HTTP request in 0.5sec multipliers

Members of the tls object​

NameTypeDescription
empString(optional) Ephemeral public key (transport key)
keyString(optional) Encrypted private key
crtStringBase64 encoded DER x509 certificate

Response status code​

{
"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
}

Response data for successful operation​

NameTypeDescription
csrStringRequested x509 CSR, base64 encoded DER file.
genuineStringAttestation data.
reboot_requiredBoolTrue if a reboot is required for changes to take effect.
updatedBoolTrue is configuration have been changed.

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CONFIG_UPDATEDLOG_RESULT_OK200
LOG_TYPE_CONFIG_UPDATEDLOG_RESULT_FAILED406

Get device attestation data​

info

This endpoint is available only on Encedo PPA.

info

This endpoint is ignoring access scope, effectively any scope value is allowed as long as the JWT_TOKEN is valid.

info

The Authorization header is not required on fresh, not personalised devices.

Device attestation​

GEThttps://my.ence.do/api/system/config/attestation

Obtain device attestation data, which serves as proof of genuineness.

Headers​

NameTypeDescription
AuthorizationStringBearer JWT_TOKEN

Response status code​

{
"crt": "MIICATCCAaagAwIBAgIBbTAKBggqhkjOPQQDAjBCMQswCQYDVQQGEwJVSzEXMBUGA1UECgwORW5jZWRvIExpbWl0ZWQxGjAYBgNVBAMMEUVuY2VkbyBDdXN0b2R5IENBMB4XDTIwMTAwNTE5MjkzM1oXDTIzMTAwNTE5MjkzM1owQDELMAkGA1UEBhMCVUsxEzARBgNVBAoMCkVuY2VkbyBMdGQxHDAaBgNVBAMMEyMwMTIzZWI1NjFmNWVhMDczZWUwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASdUuVLRdTcTd1DSu/6qTdh562q5WsXGEcHBP/gpUvHcU/501HwR2NybMmFQQ7/HgLgCYgaTPE+kvq6Lb0AuRf/o4GOMIGLMA4GA1UdDwEB/wQEAwIHgDAJBgNVHRMEAjAAMB0GA1UdDgQWBBSqAknAzbCHMuji+7pJhSslHyuApTAfBgNVHSMEGDAWgBR5VVeOla0ntTsGycLKHAI2qA58BjAuBgNVHREEJzAloCMGCSsGAQQBg7cnAaAWBBRGRaJpZ1sXy+HKN/vFyusw810N+DAKBggqhkjOPQQDAgNJADBGAiEA7un6HD6upjiPmhCLYMCk3fxNZyx6cZMNWzQV7LozMTMCIQDptL4bvTeMymy5WiGKrFPkDv7f+Nz9x5vop9vZry0N1Q==",
"genuine": "qgJJwM2whzLo4vu6SYUrJR8rgKU=.MTY0NzY0MTI4NQ==.MEYCIQCYDC9IDlnGlkBI7/1YPMSIC/31nfiFUISpWEb3Pw5vAgIhAPIcyOufL4MQPwl/dUpM4W8gi+IECx9i9m1LcSHo8Bqo"
}

Response data for successful operation​

NameTypeDescription
crtStringBase64 encoded DER x509 device certificate.
genuineStringAttestation data.

Factory provisioning​

info

This endpoint is available only on Encedo PPA.

danger

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​

POSThttps://my.ence.do/api/system/config/provisioning

On factory Secure Enclave provisioning (on Encedo PPA only).

Headers​

NameTypeDescription
Content-Type*Stringapplication/json

Request Body​

NameTypeDescription
crt*Stringx509 certificate
genuine*StringAttestation data

Response status code​

No response body.