Registration

Those endpoints allow to register a external authenticator, like Encedo Mobile Authenticator.

Allowed users

User

Allowed

Master

ExtAuth

Required access scope

Main

auth:ext:pair

Alternative

Register a new authenticator

Phase 1 - challenge

Get the registration challenge and begin the process

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

Generate a challenge to link the device with a new external authenticator.

Headers

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN
Content-Type*	String	application/json

Request Body

Name	Type	Description
epk*	String	Broker ephemeral public key

Response status code

200: Operation successful

{
  "request": "eyJlY2RoIjoieDI1NTE5IiwidHlwIjoiSldUIiwiYWxnIjoiSFMyNTYifQ.eyJqdGkiOiI5cHM0WWlySDdUZTB0ZWZwanl6Q2NQNTYzRjhTK2daeGJCTVg5VExFQnZnPSIsImV4cCI6MTY0Nzk2MzUxMCwiYXVkIjoiL05HU0F2dTltNjRpQzc5d2FrR3ZMYzdSYlcrclhkcnVZUHVlOXYwbmZIST0iLCJpc3MiOiJmZjYvcnBncHJ3Nk9qY1BiZWRJQjVMYnN4alpxbW5mNDNKMXplSzF4ODJJPSJ9.M0gYXmgB9cpI1YF48SG5iI7OcMRxRC-uqlIHaiAFrUQ",
  "eid": "ff6/rpgprw6OjcPbedIB5LbsxjZqmnf43J1zeK1x82I="
}

400: Incorrect argument(s)

401: Missing or invalid JWT_TOKEN

403: Incorrect access scope

406: Operation failed

409: Incorrect internal state

Response data for successful operation

Name	Type	Description
eid	String	EncedoID, public key of the instance.
request	String	Registration data to proxy to the external authenticator.

Log entries

Event	Result	Source
LOG_TYPE_FAILED_SCOPE_CHECK	LOG_RESULT_FAILED	403

Phase 2 - response

Upload the registration reply and validate registration

POST https://my.ence.do/api/auth/ext/validate

Upload a registration reply data sent by an external authenticator.

Headers

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN
Content-Type*	String	application/json

Request Body

Name	Type	Description
pid*	String	Unique Pairing ID
reply*	String	Reply data sent by external authenticator

Response status code

200: Operation successful

{
  "kid": "42afc419dbda72636b37a2455955e095",
  "code": "3SABMB8RqE2XH2floeEqg7obeyn/TtqK1hk/hi+4N8k="
}

400: Incorrect argument(s)

401: Missing or invalid JWT_TOKEN

403: Incorrect access scope

406: Operation failed

409: Incorrect internal state

Response data for successful operation

Name	Type	Description
code	String	Confirmation code
kid	String	Key ID of saved authenticator public key

Log entries

Event	Result	Source
LOG_TYPE_FAILED_SCOPE_CHECK	LOG_RESULT_FAILED	403
LOG_TYPE_AUTH_PAIRED_EXTERNAL	LOG_RESULT_OK	200

List registered authenticators

Get authentication data

POST https://my.ence.do/api/auth/ext/mac

Obtain MAC data to authenticate the device on the broker site and retrieve a list of paired authenticators.

Headers

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN
Content-Type*	String	application/json

Request Body

Name	Type	Description
epk*	String	Broker ephemeral public key

Response status code

200: Operation successful

{
  "nonce": "XJ04YiV/Mh517cV0zqG+XEeCGbGNBt2PUnWcCtV7NVg=",
  "mac": "ttyTJLTi+bguIwU9mW+5dCEy6l55YyQZZ4tq8tR8WRE=",
  "eid": "ff6/rpgprw6OjcPbedIB5LbsxjZqmnf43J1zeK1x82I="
}

400: Incorrect argument(s)

401: Missing or invalid JWT_TOKEN

403: Incorrect access scope

406: Operation failed

409: Incorrect internal state

Response data for successful operation

Name	Type	Description
eid	String	EncedoID, public key of the instance.
mac	String	Authentication data
nonce	String	Authentication data nonce

Log entries

Event	Result	Source
LOG_TYPE_FAILED_SCOPE_CHECK	LOG_RESULT_FAILED	403