Version: 8.2411.x.x RR

Device Service

This chapter describes the Device Service. The Device Service is not a standard FIDO service, but a proprietary nevisFIDO functionality.

info

The Device Service is an HTTP API to be used by the Nevis Mobile Authentication SDK, so it is aimed for mobile applications. Other applications, such as administration web applications, should not try to use it. It is presented here for reference.

This service is in experimental state and can be modified or dropped in future releases without notice.

Android SDK 3.6.1 / 3.6.2 device identifier issue

Registrations created with Android SDK 3.6.1 and 3.6.2 resulted in a non-unique device identifier.

Due to this, Android SDK 3.7.0 will not query these endpoints for affected users.

Refer to the issue description for details.

A device represents a mobile device. A mobile device has FIDO UAF credentials and dispatch targets. The Authentication Mobile SDK allows the definition of multiple accounts in a device and thus the FIDO UAF credentials and dispatch targets of a device can be associated with multiple identities.

The Device Service consists of three parts or endpoints: the Get, Modify and Delete Device.

Get Device Credentials

This section describes the Get Device Credentials part of the Device Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/devices/credentials/{deviceId}

deviceId is the identifier of the device to be retrieved.

HTTP Methods

GET is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

Name	Description
`Device-Signature`	The `Device-Signature` value is a JWS (JSON Web Signature) using compact serialization. It must be signed with the signature key of a dispatch target defined in the device.
`Accept`	Accept header, must be `application/jose;charset=UTF-8`.

The payload of the JWS in the Device-Signature has the following format:

Attribute	Type	Description	Optional
`dispatchTargetId`	String	The identifier of the dispatch target that was used to sign this JSON payload.	false
`requestId`	String	A unique identifier for this JSON payload. It can contain up to 64 characters.	false
`creationTimeInEpochMillis`	Number	The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false

Response Headers

The following response headers will be set:

Name	Description
`Content-Type`	Content type header, fixed to `application/jose;charset=UTF-8`.

Invalid JWS Error

If there is a big divergence between the clock of nevisFIDO and the clock of the mobile device, the server will refuse to accept the request. If this is detected, the content of the WWW-Authenticate header will be:

JWS error="device_signature_expired", error_description="The device signature expired"

By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.

Response Body

The body of the response message is encrypted using the standard JWE using compact serialization. The contents can only be decrypted using the encryption key of the dispatch target that signed the contents of the Device-Signature header.

The response contains the information of the device. The format of the decrypted payload is:

Attribute	Type	Description
`deviceId`	String	The identifier of the device.
`fidoUafCredentials`	Array	An array containing `FidoUafCredential` (see below) objects.
`dispatchTargets`	Array	An array containing `DispatchTarget` (see below) objects.

The FidoUafCredential format is:

Attribute	Type	Description
`keyId`	String	The key identifier of the FIDO UAF credential. It is encoded in base 64 URL.
`aaid`	String	The AAID of the authenticator associated with this FIDO UAF credential.

The DispatchTarget format is:

Attribute	Type	Description
`id`	String	The identifier of the dispatch target.
`name`	String	The user-friendly name of the dispatch target.
`target`	String	The target (FCM registration target) of the dispatch target. It will not be present if there is no target defined for the dispatch target.

Example Request

GET /nevisfido/devices/dc210afa-cce6-4192-8780-bc1b11dfdbd1 HTTP/1.1
Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiYmUzYzhiZjgtODE4NC00YTY5LWFiNzYtOGEzNzdlODYyYzRlIiwicmVxdWVzdElkIjoiZTQ5YWEyNjUtOTMxNC00OTI4LWEyNjItZGEyMThlN2IzZTgzIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg3MDQ1OH0.IG8_15_AmWqVJSr7VtwIOvJLZMrXCXi0SNDgz4B_qmW-8dXjAASzAFQN04nL7quNKc2rP1nzE2f-64DS9sQGK9G8nbvMlKXTxPb4-iv38mKJcaKTrLVBwm3NvZaUeOpUkBEWtUH0ekGA1YjHsazvHB9nKFaeejNRjDbLFOXY1QVlQytiE6ZCfkEVLALpehfsRBZIYnRDOyA3Z2aVpIpAKLLWShfDqsyxZ0b2bIi8xmteq3ax-ntddxQpJsNkD_nA7nv-1MGWHwoyM5LJ5XXHkIm3N6pXGxBoJdyW8Qsok_gmELLDX1cIQbNfTQFraHpc7ucoQ0URXHJ3tJsL_L5HhQ
Accept: application/jose;charset=UTF-8
Host: fido.siven.ch

cURL:

$ curl 'https://fido.siven.ch/nevisfido/devices/dc210afa-cce6-4192-8780-bc1b11dfdbd1' -i -X GET \
    -H 'Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiYmUzYzhiZjgtODE4NC00YTY5LWFiNzYtOGEzNzdlODYyYzRlIiwicmVxdWVzdElkIjoiZTQ5YWEyNjUtOTMxNC00OTI4LWEyNjItZGEyMThlN2IzZTgzIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg3MDQ1OH0.IG8_15_AmWqVJSr7VtwIOvJLZMrXCXi0SNDgz4B_qmW-8dXjAASzAFQN04nL7quNKc2rP1nzE2f-64DS9sQGK9G8nbvMlKXTxPb4-iv38mKJcaKTrLVBwm3NvZaUeOpUkBEWtUH0ekGA1YjHsazvHB9nKFaeejNRjDbLFOXY1QVlQytiE6ZCfkEVLALpehfsRBZIYnRDOyA3Z2aVpIpAKLLWShfDqsyxZ0b2bIi8xmteq3ax-ntddxQpJsNkD_nA7nv-1MGWHwoyM5LJ5XXHkIm3N6pXGxBoJdyW8Qsok_gmELLDX1cIQbNfTQFraHpc7ucoQ0URXHJ3tJsL_L5HhQ' \
    -H 'Accept: application/jose;charset=UTF-8'

The payload inside the JWS of the Device-Signature header:

{
  "dispatchTargetId" : "be3c8bf8-8184-4a69-ab76-8a377e862c4e",
  "requestId" : "e49aa265-9314-4928-a262-da218e7b3e83",
  "creationTimeInEpochMillis" : 1700726870458
}

Example Response

HTTP/1.1 200 OK
Date: Thu, 23 Nov 2023 08:07:50 GMT
Content-Type: application/jose;charset=UTF-8
Content-Length: 859

eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.SiJ1iw5RyiZNnf3m75K_xA-c7nNKjgCykdk1HiCV1gSH1uzp8L60pLmx-yJJGZXoPPpKM_AIjE9u_Q1cKk53Ms7YsUiCWNrs3YE-Ag3MUNt5zokGEx4WgOW9UH30XXBOd8UJdxaHHHqhcn7lobv5TQwUmoaLCFTh4oYIiky3SQooSODE0pItnXCAySd65GSGvYfVTd3CT6l74mBXEM3OcHiyHJxu6aRUzFDnOKiL_pBsdq6fe2s2Do5KhYAZdWPN8RdyTAmyK6wvgU40LLl0BmbEGksN4GLl3b4fXMVrE_j3sHRR5AEUbp5OTrgNC5gIipYDztMw-SPyAju074PJjg.ov12iXmAKOqfutco.-MJ278nBxlXjfo8lSrmGgu4TWgsVFpMnJAquSo2I78kvvcJMrOi1nUf0w8WsAU5dMdeoRCpDTHYlcVzRS_WnYcTIU6fWlglSKNgHNAcIkVnjemhhMF_VglNUjqVQcSJfwi6CI7MXJK8kCkxNenNd2uNIxdooiaj_LlLX_jMrOe-R54TK4ThoQ6e61vRNdjPWMJ_m3YDxb-3HSMvJs7qJvOoz8zcgwKzQ7yEeet3sP7yli7DAJQGg_ZKD6CgRWC53qZpS7jH-bTiFRFizHZLA8S_kmj_xw-fnWirJt_mGA0nbktN8SDF6adrbYuA338Rq_F-_45kCgPQmG5MMR1xgx633fzWlWIHxi1B55yLLxB-50TTuMBgdiTKxEeelflhsIn_ihVIfNGZRygaUxz3Ek2qGI38Tt5lQB7Xq_Q7L.OZv_j8miGp7yS0ntpc73iw

The decrypted JWE in the body is:

{
  "deviceId" : "e5ed8c10-3fad-46c2-9261-d6b1a8166593",
  "fidoUafCredentials" : [ {
    "keyId" : "dGhpc2lzdGhla2V5SUQx",
    "aaid" : "F1D0#0001"
  }, {
    "keyId" : "dGhlIGtleUlEIDI",
    "aaid" : "F1D0#0003"
  } ],
  "dispatchTargets" : [ {
    "id" : "d22e5c94-3bcf-4dbc-ac10-27cfdd421de0",
    "name" : "My Android home phone",
    "target" : "921207f5-b0e0-46a5-a05d-b52318a96e07"
  } ]
}

HTTP Status Codes

The following HTTP status codes are returned by the Get Device Credentials part/endpoint of the Device Service:

HTTP Code	Description
200	Ok The server successfully found the device information.
400	Bad Request The JWS in the `Device-Signature` header is not properly formatted.
401	Unauthorized The request was not authorized. The provided JWS in the `Device-Signature` header is not valid.
403	Forbidden The dispatch target used to sign the JWS of the `Device-Signature` header is not part of the requested device.
406	Not Acceptable The `Accept` header is not properly set to `application/jose;charset=UTF-8`.
500	Internal Server Error The server could not process the request because of an unexpected error.

Modify Device Credentials

This section describes the Modify Credentials part of the Device Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/devices/credentials/{deviceId}

deviceId is the identifier of the device to be modified.

HTTP Methods

PATCH is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

Name	Description
`Content-Type`	Content type header, must be `application/jose;charset=UTF-8`.

Request Body

The Modify Dispatch Target Service body is a JWS (JSON Web Signature) using compact serialization. The JWS must be signed with the private key of a dispatch target defined in the device.

eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJzaWduaW5nRGlzcGF0Y2hUYXJnZXRJZCI6IjcxMjBhODliLTMyZjItNDRiMi05Yzg4LWE4YmI0YjA1ZWM3MCIsInJlcXVlc3RJZCI6ImIxYmZlZWRmLWEwMDUtNDliYy04MjY2LTRjZmY4Mzg3YWUyYSIsImNyZWF0aW9uVGltZUluRXBvY2hNaWxsaXMiOjE3MDA3MjY4NzA3MjEsIm5hbWUiOiJNeSBuZXcgUGhvbmUiLCJ0YXJnZXQiOiJlMjdhMzE0NC1kMDRiLTQzYzctYWYwOC1lYjBhZjI0YTE5MDgiLCJvcGVyYXRpb24iOiJEaXNwYXRjaFRhcmdldFVwZGF0ZSJ9.mtC_CkOXelno9AuyfMmTdm9ZLnwGTwdpcGEh3kRnV8qSXHCurz7r6rlUZo3KR7aWWzMr28g-sFoSIxJ62Rizw_X28lUFCFQ1eXBOwMbQb-X_Avf2qGtakKVG6C3duedT6ToZOB8CPXjmddbfYfrZDGM8XIcP_4EKPeHIgKvUs9q0PFxKScNN715nR6WWkbkyXHCuspRqALQt1Cl_hPhYgTdX2mv9A56P7Cfxb7xnXeIatr25-hIDW4TjzSPJSYJKpLxQpnGdWyNt1sctLSKvmd5tVLRp_gRiejOI0Yg-UMM0jDvP3MEm79G7eImJ1UzwmOFe5Zes0vkpbTRJqzQ0wA

There are two type of modification operations that can be performed (specified by the operation attribute).

The sections below describe the payload inside the JWS for each operation.

Update Dispatch Targets

This operation will update all the dispatch targets in the device.

Attribute	Type	Description	Optional
`signingDispatchTargetId`	String	The identifier of the dispatch target that was used to sign this JSON payload.	false
`requestId`	String	A unique identifier for this JSON payload. It can contain up to 64 characters.	false
`creationTimeInEpochMillis`	Number	The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false
`operation`	String	The name of the operation. It must be set to `DispatchTargetUpdate`.	false
`name`	Array	The new value for the name to set for all the dispatch targets in the device. If not provided, no name will be modified.	true
`target`	Array	The new value for the target (FCM registration token) to set for all the dispatch targets in the device. If not provided, no target will be modified.	true

Delete FIDO UAF Credentials and Dispatch Targets

Deletes the specified FIDO UAF credentials and dispatch targets defined in the device.

Attribute	Type	Description	Optional
`signingDispatchTargetId`	String	The identifier of the dispatch target that was used to sign this JSON payload.	false
`requestId`	String	A unique identifier for this JSON payload. It can contain up to 64 characters.	false
`creationTimeInEpochMillis`	Number	The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false
`operation`	String	The name of the operation. It must be set to `Delete`.	false
`keyIds`	Array	An array with the key IDs of the FIDO UAF credentials to be removed. The key IDs are expressed as base 64 URL strings.	true
`dispatchTargetIds`	Array	An array with the identifiers (IDs) of the dispatch targets to be removed.	true

Update Device ID

This operation will update the device identifier of the specified FIDO UAF credentials and dispatch targets.

Attribute	Type	Description	Optional
`signingDispatchTargetId`	String	The identifier of the dispatch target that was used to sign this JSON payload.	false
`requestId`	String	A unique identifier for this JSON payload. It can contain up to 64 characters.	false
`creationTimeInEpochMillis`	Number	The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false
`operation`	String	The name of the operation. It must be set to `DeviceIdUpdate`.	false
`deviceId`	String	The new device ID.	false
`fidoUafCredentials`	Array	An array with the AaidAndKeyId[] (see AAID and Key ID dictionary for details) pairs of the FIDO UAF credentials to be updated.	true
`dispatchTargetIds`	Array	An array with the identifiers (IDs) of the dispatch targets to be updated.	true

AAID And Key ID Dictionary

Attribute	Type	Description	Optional
`aaid`	String	The AAID of the credential to be updated.	false
`keyid`	String	The base64url-encoded value of the key ID of the credential to be updated.	false

Response Headers

The response message has no body. Therefore, no headers will be set in the response, except if there is a big divergence between the clock of nevisFIDO and the clock of the mobile device. In this case, the server will refuse to accept the request. If this is detected, the content of the WWW-Authenticate header will be:

JWS error="device_signature_expired", error_description="The device signature expired"

By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.

Response Body

The response message has no body.

Example Request

PATCH /nevisfido/devices/9ddaaccf-8985-45f5-b201-c8fcdeb34aae HTTP/1.1
Content-Type: application/jose;charset=UTF-8
Host: fido.siven.ch
Content-Length: 740

eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJzaWduaW5nRGlzcGF0Y2hUYXJnZXRJZCI6IjcxMjBhODliLTMyZjItNDRiMi05Yzg4LWE4YmI0YjA1ZWM3MCIsInJlcXVlc3RJZCI6ImIxYmZlZWRmLWEwMDUtNDliYy04MjY2LTRjZmY4Mzg3YWUyYSIsImNyZWF0aW9uVGltZUluRXBvY2hNaWxsaXMiOjE3MDA3MjY4NzA3MjEsIm5hbWUiOiJNeSBuZXcgUGhvbmUiLCJ0YXJnZXQiOiJlMjdhMzE0NC1kMDRiLTQzYzctYWYwOC1lYjBhZjI0YTE5MDgiLCJvcGVyYXRpb24iOiJEaXNwYXRjaFRhcmdldFVwZGF0ZSJ9.mtC_CkOXelno9AuyfMmTdm9ZLnwGTwdpcGEh3kRnV8qSXHCurz7r6rlUZo3KR7aWWzMr28g-sFoSIxJ62Rizw_X28lUFCFQ1eXBOwMbQb-X_Avf2qGtakKVG6C3duedT6ToZOB8CPXjmddbfYfrZDGM8XIcP_4EKPeHIgKvUs9q0PFxKScNN715nR6WWkbkyXHCuspRqALQt1Cl_hPhYgTdX2mv9A56P7Cfxb7xnXeIatr25-hIDW4TjzSPJSYJKpLxQpnGdWyNt1sctLSKvmd5tVLRp_gRiejOI0Yg-UMM0jDvP3MEm79G7eImJ1UzwmOFe5Zes0vkpbTRJqzQ0wA

cURL:

$ curl 'https://fido.siven.ch/nevisfido/devices/9ddaaccf-8985-45f5-b201-c8fcdeb34aae' -i -X PATCH \
    -H 'Content-Type: application/jose;charset=UTF-8' \
    -d 'eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJzaWduaW5nRGlzcGF0Y2hUYXJnZXRJZCI6IjcxMjBhODliLTMyZjItNDRiMi05Yzg4LWE4YmI0YjA1ZWM3MCIsInJlcXVlc3RJZCI6ImIxYmZlZWRmLWEwMDUtNDliYy04MjY2LTRjZmY4Mzg3YWUyYSIsImNyZWF0aW9uVGltZUluRXBvY2hNaWxsaXMiOjE3MDA3MjY4NzA3MjEsIm5hbWUiOiJNeSBuZXcgUGhvbmUiLCJ0YXJnZXQiOiJlMjdhMzE0NC1kMDRiLTQzYzctYWYwOC1lYjBhZjI0YTE5MDgiLCJvcGVyYXRpb24iOiJEaXNwYXRjaFRhcmdldFVwZGF0ZSJ9.mtC_CkOXelno9AuyfMmTdm9ZLnwGTwdpcGEh3kRnV8qSXHCurz7r6rlUZo3KR7aWWzMr28g-sFoSIxJ62Rizw_X28lUFCFQ1eXBOwMbQb-X_Avf2qGtakKVG6C3duedT6ToZOB8CPXjmddbfYfrZDGM8XIcP_4EKPeHIgKvUs9q0PFxKScNN715nR6WWkbkyXHCuspRqALQt1Cl_hPhYgTdX2mv9A56P7Cfxb7xnXeIatr25-hIDW4TjzSPJSYJKpLxQpnGdWyNt1sctLSKvmd5tVLRp_gRiejOI0Yg-UMM0jDvP3MEm79G7eImJ1UzwmOFe5Zes0vkpbTRJqzQ0wA'

The payload inside the JWS for the update dispatch targets operation:

{
  "signingDispatchTargetId" : "7120a89b-32f2-44b2-9c88-a8bb4b05ec70",
  "requestId" : "b1bfeedf-a005-49bc-8266-4cff8387ae2a",
  "creationTimeInEpochMillis" : 1700726870721,
  "name" : "My new Phone",
  "target" : "e27a3144-d04b-43c7-af08-eb0af24a1908",
  "operation" : "DispatchTargetUpdate"
}

The payload inside the JWS for the delete FIDO UAF credentials and dispatch targets operation:

{
  "signingDispatchTargetId" : "d0de0bd2-4ee7-4b1b-bfcb-7555001c717a",
  "requestId" : "9a6680d1-48b5-46cb-91ed-f1fa612ede36",
  "creationTimeInEpochMillis" : 1700726870820,
  "dispatchTargetIds" : [ "6594fa3e-bec2-460f-b505-e0b8a05e534b", "d92a26b6-3321-48ba-9c7f-33511266ce1d" ],
  "keyIds" : [ "NmUwNTYzMzUtMmI2Ny00NmM2LWIwMjgtMzk4MjhjYzk4YTA3" ],
  "operation" : "Delete"
}

Example Response

HTTP/1.1 204 No Content
Date: Thu, 23 Nov 2023 08:07:50 GMT

HTTP Status Codes

The following HTTP status codes are returned by the Modify Device Credentials part/endpoint of the Dispatch Target Service:

HTTP Code	Description
204	No Content The server successfully modified the device information.
400	Bad Request The provided payload is not properly formatted.
401	Unauthorized The request was not authorized. It was not possible to verify the signature of the request.
403	Forbidden The dispatch target used to sign the JWS is not part of the requested device.
415	Unsupported Media Type The `Content-Type` header is not properly set to `application/jose;charset=UTF-8`.
422	Unprocessable Entity The request could not be processed. For example, because the provided name in the dispatch target modification is already in use by another dispatch target of the user.
500	Internal Server Error The server could not process the request because of an unexpected error.

Delete Device Credentials

This section describes the Delete Device Credentials part of the Device Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/devices/credentials/{deviceId}

deviceId is the identifier of the device to be deleted.

HTTP Methods

DELETE is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

Name	Description
`Device-Signature`	The `Device-Signature` value is a JWS (JSON Web Signature) using compact serialization. It must be signed with the signature key of a dispatch target defined in the device.

The payload of the JWS in the Device-Signature has the following format:

Attribute	Type	Description	Optional
`dispatchTargetId`	String	The identifier of the dispatch target that was used to sign this JSON payload.	false
`requestId`	String	A unique identifier for this JSON payload. It can contain up to 64 characters.	false
`creationTimeInEpochMillis`	Number	The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false

Response Headers

JWS error="device_signature_expired", error_description="The device signature expired"

By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.

Response Body

The response message has no body.

Example Request

DELETE /nevisfido/devices/73ff33b7-e43a-4efb-8abc-58c9629c72e2 HTTP/1.1
Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiOGZiZGY0MjktNzQ4Ny00NjhjLWJmZjctODU4MjdkOTdhYjZlIiwicmVxdWVzdElkIjoiYWMwNGYzMTAtYjliZi00MDE1LTljMGEtNDMwYzYwNjFmZDJlIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg2ODk2M30.i1AyFTlvsEH2go1bjS91c3uA6czhyY0IkVC_OEkfkbWPsp6NnMtwbFGgryG3Io4gIVONviE87oP7Z3Mtiq4SKR03SaQH40G4zhQjSpvh_AR2-McurfpnlFNmIqSlYLWpyDs4ZC28iysNtUk2fvhVlI9wqTCq1zG5m853w98qFpOmzG6taDcbtBpxh2mrGSP4Sn4cScI3kbvUmky98bsubByCLdMS_YzWFBra2MrlctiBgdVQoLIy-d0l4YAsJq3IsROuEL-DfuXfRpIE7LYOfk9zW3PxfLMhUTlAXqBvzCbhPdepyI-kkyHazt1WpifsRxtzp11P1-snGJndvTdv6Q
Host: fido.siven.ch

cURL:

$ curl 'https://fido.siven.ch/nevisfido/devices/73ff33b7-e43a-4efb-8abc-58c9629c72e2' -i -X DELETE \
    -H 'Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiOGZiZGY0MjktNzQ4Ny00NjhjLWJmZjctODU4MjdkOTdhYjZlIiwicmVxdWVzdElkIjoiYWMwNGYzMTAtYjliZi00MDE1LTljMGEtNDMwYzYwNjFmZDJlIiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwMDcyNjg2ODk2M30.i1AyFTlvsEH2go1bjS91c3uA6czhyY0IkVC_OEkfkbWPsp6NnMtwbFGgryG3Io4gIVONviE87oP7Z3Mtiq4SKR03SaQH40G4zhQjSpvh_AR2-McurfpnlFNmIqSlYLWpyDs4ZC28iysNtUk2fvhVlI9wqTCq1zG5m853w98qFpOmzG6taDcbtBpxh2mrGSP4Sn4cScI3kbvUmky98bsubByCLdMS_YzWFBra2MrlctiBgdVQoLIy-d0l4YAsJq3IsROuEL-DfuXfRpIE7LYOfk9zW3PxfLMhUTlAXqBvzCbhPdepyI-kkyHazt1WpifsRxtzp11P1-snGJndvTdv6Q'

The payload inside the JWS of the Device-Signature header:

{
  "dispatchTargetId" : "8fbdf429-7487-468c-bff7-85827d97ab6e",
  "requestId" : "ac04f310-b9bf-4015-9c0a-430c6061fd2e",
  "creationTimeInEpochMillis" : 1700726868963
}

Example Response

HTTP/1.1 204 No Content
Date: Thu, 23 Nov 2023 08:07:49 GMT

HTTP Status Codes

The following HTTP status codes are returned by the Delete Device Credential part/endpoint of the Dispatch Target Service:

HTTP Code	Description
204	No Content The server successfully deleted device information.
400	Bad Request The JWS in the `Device-Signature` header is not properly formatted.
401	Unauthorized The request was not authorized. The provided JWS in the `Device-Signature` header is not valid.
403	Forbidden The dispatch target used to sign the JWS of the `Device-Signature` header is not part of the requested device.
500	Internal Server Error The server could not process the request because of an unexpected error.

Get Device Out-of-Band Operations

This section describes the Get Device Out-of-Band Operations part of the Device Service.

It is used to retrieve the out-of-band operations that have not timed-out and whose token has not been redeemed.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/devices/oobOperations/{deviceId}

deviceId is the identifier of the device associated with the operations to be retrieved.

HTTP Methods

GET is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

Name	Description
`Device-Signature`	The `Device-Signature` value is a JWS (JSON Web Signature) using compact serialization. It must be signed with the signature key of a dispatch target defined in the device.
`Accept`	Accept header, must be `application/jose;charset=UTF-8`.

The payload of the JWS in the Device-Signature has the following format:

Attribute	Type	Description	Optional
`dispatchTargetId`	String	The identifier of the dispatch target that was used to sign this JSON payload.	false
`requestId`	String	A unique identifier for this JSON payload. It can contain up to 64 characters.	false
`creationTimeInEpochMillis`	Number	The creation time of this JSON payload. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false

Response Headers

The following response headers will be set:

Name	Description
`Content-Type`	Content type header, fixed to `application/jose;charset=UTF-8`.

Invalid JWS Error

JWS error="device_signature_expired", error_description="The device signature expired"

By default, the server will accept a divergence of 5 minutes. If you want to modify this value, update the fido-uaf.timeout.device-request parameter in the nevisFIDO configuration.

Response Body

The response contains the information of the device. The format of the decrypted payload is:

Attribute	Type	Description
`deviceId`	String	The identifier of the device.
`operations`	Array	An array containing `DeviceOobOperation` (see below) objects.

The DeviceOobOperation format is:

Attribute	Type	Description	Optional
`creationTimeInEpochMillis`	Number	The creation time of the operation. The time is expressed as UNIX time: time by the number of milliseconds that have elapsed since 00:00:00 UTC on 1 January 1970, the Unix epoch.	false
`dispatcher`	String	The name of the dispatcher for the operation. `firebase-cloud-messaging` for push messages, `png-qr-code` for QR code, `link` for an operation transmitted through a URL.	false
`outOfBandPayload`	String	The JSON string containing the out-of-band payload. This value can be provided to the Nevis Mobile SDK to obtain an `OutOfBandPayload` object.	false
`additionalInformation`	String	The additional information provided to the dispatcher. Currently this only contains the value of the notification when the Firebase Cloud Messaging dispatcher has been used with the operation.	true

Example Request

GET /nevisfido/devices/oobOperations/baf18de4-0b9e-498f-bd40-1c2468957f58 HTTP/1.1
Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiZjI1NmYyZDMtYWYyOS00NjE4LWFmMmYtNmQ4MWI5ZGYwNzkzIiwicmVxdWVzdElkIjoiZjc3OGMyMjctMzE1Yi00YjkzLTkzMGItZjVhOWVmMmFjMjU3IiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwNjcwOTkwMjY4OH0.OxCcv1rtE4Whcai-QF5h-Pjkh1OjdfnEuywP46Emb9uDBQt_y7TuKjGc9OUfMMM1k5YCi7E9KT_qTdQwV202R-OKtlp8CKmLIag_4Kdz22i9SmDKy_BH4nfrC2swROoYbnmGsMfua39xgygbORgOJaOcHcFwG0CWcD-O31Par532TO-E-wDv2ZPXWxC_RAD_qDKKYG9DA72FRPj-teI43cBnRxknUCa9ogh-oqWmGb7VH_h6xNogpxosFpIggQJksCpHt1oNGB0VlPfYUNhLl6QnyGXpUAJipgq3T3Rp4J1WLJCQjWQd7SdIfPQCKcwH1As59lKi1ybzhRQ5vLYzVQ
Accept: application/jose;charset=UTF-8
Host: fido.siven.ch

cURL:

$ curl 'https://fido.siven.ch/nevisfido/devices/oobOperations/baf18de4-0b9e-498f-bd40-1c2468957f58' -i -X GET \
    -H 'Device-Signature: eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJkaXNwYXRjaFRhcmdldElkIjoiZjI1NmYyZDMtYWYyOS00NjE4LWFmMmYtNmQ4MWI5ZGYwNzkzIiwicmVxdWVzdElkIjoiZjc3OGMyMjctMzE1Yi00YjkzLTkzMGItZjVhOWVmMmFjMjU3IiwiY3JlYXRpb25UaW1lSW5FcG9jaE1pbGxpcyI6MTcwNjcwOTkwMjY4OH0.OxCcv1rtE4Whcai-QF5h-Pjkh1OjdfnEuywP46Emb9uDBQt_y7TuKjGc9OUfMMM1k5YCi7E9KT_qTdQwV202R-OKtlp8CKmLIag_4Kdz22i9SmDKy_BH4nfrC2swROoYbnmGsMfua39xgygbORgOJaOcHcFwG0CWcD-O31Par532TO-E-wDv2ZPXWxC_RAD_qDKKYG9DA72FRPj-teI43cBnRxknUCa9ogh-oqWmGb7VH_h6xNogpxosFpIggQJksCpHt1oNGB0VlPfYUNhLl6QnyGXpUAJipgq3T3Rp4J1WLJCQjWQd7SdIfPQCKcwH1As59lKi1ybzhRQ5vLYzVQ' \
    -H 'Accept: application/jose;charset=UTF-8'

The payload inside the JWS of the Device-Signature header:

{
  "dispatchTargetId" : "f256f2d3-af29-4618-af2f-6d81b9df0793",
  "requestId" : "f778c227-315b-4b93-930b-f5a9ef2ac257",
  "creationTimeInEpochMillis" : 1706709902688
}

Example Response

HTTP/1.1 200 OK
Date: Wed, 31 Jan 2024 14:05:02 GMT
Content-Type: application/jose;charset=UTF-8
Content-Length: 1626

eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.fJqZWT_uANHsMhw628ymd-_zov1GeRV_J--__mMt_ciwCNeyDlMqINHCw-DtL8zhNh184OFFwPKSnOquEqDLG_ppeaCd_9Hexs33ODzvhIMqQW_lsSH_DHxD5Su8JTtpqNXIo3H7QymIatwhMgozB8Q15_5rMoabLzbcrU8TsPdvMA15dRa4suLS1V9x8UPbHPZLSrEoKVDJQx01FPb3zMSFEPQlQMITp9QnkoLLTE6PWqzbFgb9FlMafl5tMlhyxVdw5NueM7lLr3vhaMnpKEEgFnM_bnsb3FrpYXHgHCsRY1NLwZ6qQI1-TY7ELCIKKaspLRnRY729pQYmSpKpaQ.dFBaUSCaoD1Tkwd0.l_Cva9IA-ENGDjx7kIFgg9q6lnPUFmjhRLmGSkRHna95cwKMBYe3X3QBiOlawMyVBZ8YH_wQlav1UHgX8uUl0o3itD9yNWUESAyN3Soh5YlJGEnSk8rawqQbse_vk60TO-2a5G8LGVn3j21T70k3mMf148sVX-jzGPeRPLfkz1mHIKIx3aI0sLkp-6wLP__Wz0SpRGpix3brUte1bRXxjB9Bv9wnqUG77WyMZyZmf5ev98pP_uu4pLI-mE_V8jjVAhjveUThV2XE2XXG5LHI-WMzh2dZ7i0Htrxfz_a-eBYJ9FBetCy3b9XwMzLrp56SQOI0CEJHX6QDhevqeRCkB26dRJTHYcRjbhJh8cV5XDdeZdrTOTbnA_WtX4pCrg5_l3yv5C5Ru03z3p7RaafmPyv9Icd0vHzlX7SJLja6mgrLU8Ru2OQlHwI7EMO8-QReC9GuPwUYeDXthXDAfq4ubiOLKeFG7Cs1k5OWuXa4H1GKWLHHU1Lod3AVjMRoC3vqec-zrAlU9jRSFD-anlH1-FrKXVfC38zY1qNN4vS3Es-qK_UhFZ-ryCdaisW52HfSkTXi6LaDzHgGUV3NfipgVinCIPkHJXL_jbiN42IIhFUQzGT4UF_5ODYgrnoVJtzHmHD47-HsIpTiO267J9HfpWZHyGWgYF7oWK09N6XPH37bG_c1a2124IHPSsD0mwpxnqVSxkoLD-pDOkfrDn5LRTuDJRVdOdaFi_Iale3sG5a4bynzRzFBnMiRrwO57EE3NMneFIzj2tYXZVG3XHOGP5SVfNMJQFdYUJ-C49tjfo87UxGddTfrEvGzSU_orG1zRJtcnngFK6C9ArmYktmQL_UrFuBAPuOtFfsJkKRjaxNR_nKvTk6OljAKy0DKPHP33tdv75YFzU292SolnSFKaNFlnG_Pz3NoWqRNSya7EMR6EOT-FdLUkTQAQEWa6sQclxOxDsTGM-RYykUhLv6HUfAN8Fhdjqoe9FVrdYQmWjfnDvO9SIZTpsLyckCi71N3XNQuteRfuVWbLRtlvFnQMgdd5j6-2FupJymIJM9NOKrpNoFRejLUAc4q4-404_FnO0kYVPyUfxYPU2BLMJdxrhfgWITyScWNjWFOz_z7JPcigkvIodQ-DHAb4M6bfyTUU7o-i8E-aYjbaseYE4jEf1dcXgE9-q2e6R86wM0.1hjpZj-Ocx4trKVFGr5Tjg

The decrypted JWE in the body is:

{
  "deviceId" : "62ced878-6720-4278-aaf9-ecb0207adb79",
  "operations" : [ {
    "dispatcher" : "firebase-cloud-messaging",
    "outOfBandPayload" : {
      "nma_data" : {
        "token" : "0e88d42d-8e2a-498d-8cdc-3caaa274a45f",
        "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
        "attributeName" : "some additional data included in the push notification"
      },
      "nma_data_content_type" : "application/json",
      "nma_data_version" : "1"
    },
    "additionalInformation" : {
      "notification" : {
        "title" : "Dirk Gently Bank - Confirm the payment"
      }
    },
    "creationTimeInEpochMillis" : 1706709902722
  }, {
    "dispatcher" : "png-qr-code",
    "outOfBandPayload" : {
      "nma_data" : {
        "token" : "2850d884-eb30-49f6-823d-1fabfd8f6bd3",
        "redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication",
        "attributeName" : "some additional data included in the QR code"
      },
      "nma_data_content_type" : "application/json",
      "nma_data_version" : "1"
    },
    "creationTimeInEpochMillis" : 1706709902722
  } ]
}

HTTP Status Codes

The following HTTP status codes are returned by the Get Device Out-of-Band Operations endpoint of the Device Service:

HTTP Code	Description
200	Ok The server successfully found the out-of-band operations associated with the device.
400	Bad Request The JWS in the `Device-Signature` header is not properly formatted.
401	Unauthorized The request was not authorized. The provided JWS in the `Device-Signature` header is not valid.
403	Forbidden The dispatch target used to sign the JWS of the `Device-Signature` header is not part of the requested device.
406	Not Acceptable The `Accept` header is not properly set to `application/jose;charset=UTF-8`.
500	Internal Server Error The server could not process the request because of an unexpected error.

Device Service

Get Device Credentials​

Base URL​

HTTP Methods​

Request Headers​

Response Headers​

Invalid JWS Error​

Response Body​

Example Request​

Example Response​

HTTP Status Codes​

Modify Device Credentials​

Base URL​

HTTP Methods​

Request Headers​

Request Body​

Update Dispatch Targets​

Delete FIDO UAF Credentials and Dispatch Targets​

Update Device ID​

AAID And Key ID Dictionary​

Response Headers​

Response Body​

Example Request​

Example Response​

HTTP Status Codes​

Delete Device Credentials​

Base URL​

HTTP Methods​

Request Headers​

Response Headers​

Response Body​

Example Request​

Example Response​

HTTP Status Codes​

Get Device Out-of-Band Operations​

Base URL​

HTTP Methods​

Request Headers​

Response Headers​

Invalid JWS Error​

Response Body​

Example Request​

Example Response​

HTTP Status Codes​

Get Device Credentials

Base URL

HTTP Methods

Request Headers

Response Headers

Invalid JWS Error

Response Body

Example Request

Example Response

HTTP Status Codes

Modify Device Credentials

Base URL

HTTP Methods

Request Headers

Request Body

Update Dispatch Targets

Delete FIDO UAF Credentials and Dispatch Targets

Update Device ID

AAID And Key ID Dictionary

Response Headers

Response Body

Example Request

Example Response

HTTP Status Codes

Delete Device Credentials

Base URL

HTTP Methods

Request Headers

Response Headers

Response Body

Example Request

Example Response

HTTP Status Codes

Get Device Out-of-Band Operations

Base URL

HTTP Methods

Request Headers

Response Headers

Invalid JWS Error

Response Body

Example Request

Example Response

HTTP Status Codes