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 users

User

Allowed

Master

Allowed

ExtAuth

Allowed only to call Get configuration.

Required access scope

Main

system:config

Alternative

auth:ext:pair

Operation sucessful

Get configuration

GET https://my.ence.do/api/system/config

Read the device configuration data.

Headers

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN

200: OK Operation sucessful

{
  "iat": 1647381403,
  "uts": 1647381403,
  "devid": "2023b758c209269a",
  "instanceid": "f4980240-da72-13e3-f45c-2ffbde2a1800",
  "eid": "ff6/rpgprw6OjcPbedIB5LbsxjZqmnf43J1zeK1x82I=",
  "eid_sign": "T61jY1AgV5XUW++eAcQibRDFOl5KjKwLGdo+U0def8A=",
  "user": "John Doe",
  "email": "[e-mail]",
  "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="
}

401: Unauthorized Missing or invalid JWT_TOKEN

403: Forbidden Incorrect access scope

400: Bad Request Incorrect argument(s)

406: Not Acceptable Operation failed

409: Conflict Incorrect internal state

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	DIsks0 default mode and encryption mode of Disk1 (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

POST https://my.ence.do/api/system/config

Change 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
emp	String	(optional) Ephemeral public key (transport key)
key	String	(optional) Encrypted private key
crt	String	Base64 encoded DER x509 certificate
tls consists of:	String
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

400: Bad Request Incorrect argument(s)

401: Unauthorized Missing or invalid JWT_TOKEN

403: Forbidden Incorrect access scope

406: Not Acceptable Operation failed

409: Conflict Incorrect internal state

200: OK Operation sucessful

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

Name	Type	Description
csr	String	Requested x509 CSR, base64 encoded DER file.
genuine	String	Attestation data.
reboot_required	Bool	True is reboot is required to changes takes 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 personalized devices.

Device attestation

GET https://my.ence.do/api/system/config/attestation

Get device attestation data, the proof of genuine.

Headers

Name	Type	Description
Authorization	String	Bearer JWT_TOKEN

200: OK Operation sucessful

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

401: Unauthorized Missing or invalid JWT_TOKEN

409: Conflict Incorrect internal state

Response data for successful operation

Name	Type	Description
crt	String	Base64 enceded 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 response code 406.

Factory provisioning

POST https://my.ence.do/api/system/config/provisioning

On 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

200: OK Operation sucsessful

403: Forbidden Device personalized

406: Not Acceptable Operation failed

400: Bad Request Incorrect or malformated argument(s)