Skip to main content
Version: 7.2402.x.x RR

Dispatch Target Service

This chapter describes the Dispatch Target Service. The Dispatch Target Service is not a standard FIDO service but a proprietary nevisFIDO functionality. The Dispatch Target Service is a public HTTP API with which you manage dispatch targets in nevisFIDO.

A dispatch target is a destination to which nevisFIDO can dispatch a token. For example, nevisFIDO may send push notifications with the registration token to an application in a mobile device. Here, the mobile device is the dispatch target. The dispatch target can also be an email address if the tokens are sent via an email server.

The Dispatch Target Service consists of four parts or endpoints: the Create, Modify, Delete and Query Dispatch Target.

Create Dispatch Target

This section describes the Create part of the Dispatch Target Service.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/token/dispatch/targets

HTTP Methods

POST is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

NameDescription
AcceptAccept header, must be application/json.
Content-TypeContent type header, must be application/json.

Request Body

The Create Dispatch Target Service requires a JSON payload with the following structure:

AttributeTypeDescriptionOptional
nameStringThe name describing the dispatch target. It can be used as a user-friendly representation that helps the end-user to identify this target. It must be unique for all the dispatch targets defined for the user.false
deviceIdStringThe String identifying the device (for instance a mobile phone) where the dispatch target and the FIDO UAF credentials are stored. The goal of this attribute is to allow administration tools to link the FIDO UAF credentials and the dispatch targets. This identifier should not change during the whole lifetime of the device.true
dispatcherStringThe name of the default [Dispatcher] as configured in nevisFIDO that must be associated with this dispatch target. This value corresponds to the value of the type attribute in the nevisFIDO YAML configuration. If the client does not provide the dispatcher to be used in the dispatch token request, this is the dispatcher that will be invoked. This attribute is deprecated and will be ignored in future releases.true
targetStringThe information required by the dispatcher to dispatch a token. Currently, this is only required when using the FCM dispatcher: it is the Firebase push registration token that nevisFIDO uses to send a push notification. If the FCM dispatcher is not used (i.e. if no push notifications are required), this attribute can be omitted when creating the dispatch target.true
signatureKeyObjectThe public key that is used by nevisFIDO to verify the signature of the messages sent by the client to modify the dispatch target. It must be provided as a JWS object as described in the {jws-spec}. The use attribute of the JWS must be set to sig and the key_ops attribute must contain the value sign.false
encryptionKeyObjectThe public key used by nevisFIDO to encrypt the tokens sent to the dispatch target. It must be provided as a JWS object as described in the {jws-spec}. The use attribute of the JWS must be set to enc and the key_ops attribute must contain the value encrypt.true
usernameStringIdentity information of the user whose dispatch target will be created. In the case of the idm credential repository, the accepted type of username (loginId, email or extId) depends on how the [Username Mapper] of the credential repository is configured.true

Response Headers

The following response headers will be set:

NameDescription
Content-TypeContent type header, fixed to application/json.

Response Body

The body of the response message coming from the Create Dispatch Target Service contains the identifier of the created dispatch target. If the dispatch creation was successful, the HTTP status code is "201". The table below lists all elements of the response body.

AttributeTypeDescription
idStringThe identifier of the created dispatch target. This identifier is immutable and must be used by the client to update and delete the dispatch target. It must also be used to select the dispatch target to which the generated tokens must be sent. This identifier is to be used by nevisFIDO and its format is not related to the type of the dispatcher.

Example Request

POST /nevisfido/token/dispatch/targets HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: fido.siven.ch
Content-Length: 3209

{
"name" : "My Mobile Phone",
"target" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P198aDPO",
"signatureKey" : {
"kty" : "RSA",
"x5t#S256" : "VdrYb5nzoOepus5UsKRwWPZyfUybt2ytv6lQq6e_Tyo",
"e" : "AQAB",
"use" : "sig",
"kid" : "10536191660674560031",
"x5c" : [ "MIICuzCCAaOgAwIBAgIJAJI4En4D8LAfMA0GCSqGSIb3DQEBCwUAMB0xCzAJBgNVBAYTAmNoMQ4wDAYDVQQDEwVzaXZlbjAeFw0yMjA3MjQxMzMwMzRaFw0yNDA3MjUxMzMwMzRaMB0xCzAJBgNVBAYTAmNoMQ4wDAYDVQQDEwVzaXZlbjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALGRopz8pFVpFDDtOCUILU7tMC9DepNNk4p7YBpEBQ6FNPAq9sf1uz2Q5dRtn3jGJBLNx2d82QH/c+zxw2UHYVS/UKaYHB6VBCropoklG0U7vLqhPCM+FWFmjmu+kCt0S74iucSV34ddmMwyrEEM55hX9UgUNtWqcjReLHArcYBX2WmXLC2H6EIKdOQWsGC7dt3BZPwoygzaPOjeEw7INVZ4Ymym9qXcmWqUUPgmBf/9eWIc43EIyq90HCWEhxwz5ZnmLm7uKPnfbu9OhfdnakTfhRRK7vO27pQ4JKYok4IgvoFKm3N/y/wFHFPdBYmreZ1M8UdJA5AHy2Sig+CTV3sCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAFzqFYxf2Wj4Nu1PrQ7etP9388IBZkJwYUxwpWg4Idv6+dLuheWd2aBQUzQYobkQ0fGSJo28WlAJ2drNfC+zI1/K1n8mcKGnjFDDOHay26X3EOOAFFsBm+dVDWzg/qfYgU2PM9L9dC/90FlD2ZriBF/ZF7wqz1IqOrSpgZhGIbLyDR5vOPxRdiWQDaDTY4lvhCa6bvliFJtiLkPIRonI4VOEiMmHIa59fZB9Xvx2+RmbCmGQAW+v+rZs4700AxYhPRu+wUK2BtFiFo/23vOYLaU9yk4XEXd3qya8CiP2C3e4rSu0MTr0RxWamI5f447BUQAbpgjgN5TOdD2Pu7iZ5Sg==" ],
"n" : "sZGinPykVWkUMO04JQgtTu0wL0N6k02TintgGkQFDoU08Cr2x_W7PZDl1G2feMYkEs3HZ3zZAf9z7PHDZQdhVL9QppgcHpUEKuimiSUbRTu8uqE8Iz4VYWaOa76QK3RLviK5xJXfh12YzDKsQQznmFf1SBQ21apyNF4scCtxgFfZaZcsLYfoQgp05BawYLt23cFk_CjKDNo86N4TDsg1VnhibKb2pdyZapRQ-CYF__15YhzjcQjKr3QcJYSHHDPlmeYubu4o-d9u706F92dqRN-FFEru87bulDgkpiiTgiC-gUqbc3_L_AUcU90Fiat5nUzxR0kDkAfLZKKD4JNXew"
},
"encryptionKey" : {
"kty" : "RSA",
"x5t#S256" : "URGQh2sd9ypwb2AZSNTFf711rRSDiuTnHw_HhSDB11A",
"e" : "AQAB",
"use" : "enc",
"kid" : "6997314261983703139",
"x5c" : [ "MIICujCCAaKgAwIBAgIIYRt0P3dQMGMwDQYJKoZIhvcNAQELBQAwHTELMAkGA1UEBhMCY2gxDjAMBgNVBAMTBXNpdmVuMB4XDTIyMDcyNDEzMzAzNFoXDTI0MDcyNTEzMzAzNFowHTELMAkGA1UEBhMCY2gxDjAMBgNVBAMTBXNpdmVuMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkzjtMhTSMY58vIZNocx53gGF3v9RQ3MYIa1kzqKSZPpzK8KwkHbo9yb6Wx5i0994G4HCSM9Ea6N4PKiwifRKfy4Ufznb7u/4e03w9QezQVUa6duXhjkwW5trJytoHp5F2Sc95hDTaPfPVlVC5DchjIL+p5Ay1K3lIe+RVPoVYN6CtsLTXJBAhBjtwKQHiKOq3UUbZLzOqMsrCcHXtw6gQHciWua8q4VloKO3sW4LHbeJD4cWy8IKwErtF8ShXo2vSRgeebivRXbA7OTAPEns6E0SoaMLeGdQ83dSHMQKIjY9teHua47Z9ovy5OZ1dXlDBmpKgO9FDiDK76lPYxvc5wIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQA7d7tRXcRme1IoXSfIU0Co36NI4MjB5S37eFNj0ija85nzOrD7PkbaEjTv4pu1R1T2dES/qEXP5CEqarotx625/8sYddy8YRG7emKY47P7wzNJOAOOeAzPw/PR2tYDwdg3QKzG+id8IHeSYTNwMgEpcBM7GIBEwDG9YHRGkCqY46wBJ8H9uFvNGkdzI/VTLoZP4flCf992ImP6ZCUex6MciLwJ9Lq8L7f4wbfvlcy0KhFlAbLztrjstc9g+4e6FyR49ac9STpT/qyYIuyydaGOo01mf66Mncl33emjFLh32qELryOAzVqXiXgBuNSKGO0rFGUAMplnXewG/jP2YEy/" ],
"n" : "kzjtMhTSMY58vIZNocx53gGF3v9RQ3MYIa1kzqKSZPpzK8KwkHbo9yb6Wx5i0994G4HCSM9Ea6N4PKiwifRKfy4Ufznb7u_4e03w9QezQVUa6duXhjkwW5trJytoHp5F2Sc95hDTaPfPVlVC5DchjIL-p5Ay1K3lIe-RVPoVYN6CtsLTXJBAhBjtwKQHiKOq3UUbZLzOqMsrCcHXtw6gQHciWua8q4VloKO3sW4LHbeJD4cWy8IKwErtF8ShXo2vSRgeebivRXbA7OTAPEns6E0SoaMLeGdQ83dSHMQKIjY9teHua47Z9ovy5OZ1dXlDBmpKgO9FDiDK76lPYxvc5w"
},
"username" : "username",
"deviceId" : "Acme Inc Phone. Serial Number Hash: e14c2cec1f8c448a47874b5e164df11727a9e0ad"
}

cURL:

$ curl 'https://fido.siven.ch/nevisfido/token/dispatch/targets' -i -X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"name" : "My Mobile Phone",
"target" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P198aDPO",
"signatureKey" : {
"kty" : "RSA",
"x5t#S256" : "VdrYb5nzoOepus5UsKRwWPZyfUybt2ytv6lQq6e_Tyo",
"e" : "AQAB",
"use" : "sig",
"kid" : "10536191660674560031",
"x5c" : [ "MIICuzCCAaOgAwIBAgIJAJI4En4D8LAfMA0GCSqGSIb3DQEBCwUAMB0xCzAJBgNVBAYTAmNoMQ4wDAYDVQQDEwVzaXZlbjAeFw0yMjA3MjQxMzMwMzRaFw0yNDA3MjUxMzMwMzRaMB0xCzAJBgNVBAYTAmNoMQ4wDAYDVQQDEwVzaXZlbjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALGRopz8pFVpFDDtOCUILU7tMC9DepNNk4p7YBpEBQ6FNPAq9sf1uz2Q5dRtn3jGJBLNx2d82QH/c+zxw2UHYVS/UKaYHB6VBCropoklG0U7vLqhPCM+FWFmjmu+kCt0S74iucSV34ddmMwyrEEM55hX9UgUNtWqcjReLHArcYBX2WmXLC2H6EIKdOQWsGC7dt3BZPwoygzaPOjeEw7INVZ4Ymym9qXcmWqUUPgmBf/9eWIc43EIyq90HCWEhxwz5ZnmLm7uKPnfbu9OhfdnakTfhRRK7vO27pQ4JKYok4IgvoFKm3N/y/wFHFPdBYmreZ1M8UdJA5AHy2Sig+CTV3sCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAFzqFYxf2Wj4Nu1PrQ7etP9388IBZkJwYUxwpWg4Idv6+dLuheWd2aBQUzQYobkQ0fGSJo28WlAJ2drNfC+zI1/K1n8mcKGnjFDDOHay26X3EOOAFFsBm+dVDWzg/qfYgU2PM9L9dC/90FlD2ZriBF/ZF7wqz1IqOrSpgZhGIbLyDR5vOPxRdiWQDaDTY4lvhCa6bvliFJtiLkPIRonI4VOEiMmHIa59fZB9Xvx2+RmbCmGQAW+v+rZs4700AxYhPRu+wUK2BtFiFo/23vOYLaU9yk4XEXd3qya8CiP2C3e4rSu0MTr0RxWamI5f447BUQAbpgjgN5TOdD2Pu7iZ5Sg==" ],
"n" : "sZGinPykVWkUMO04JQgtTu0wL0N6k02TintgGkQFDoU08Cr2x_W7PZDl1G2feMYkEs3HZ3zZAf9z7PHDZQdhVL9QppgcHpUEKuimiSUbRTu8uqE8Iz4VYWaOa76QK3RLviK5xJXfh12YzDKsQQznmFf1SBQ21apyNF4scCtxgFfZaZcsLYfoQgp05BawYLt23cFk_CjKDNo86N4TDsg1VnhibKb2pdyZapRQ-CYF__15YhzjcQjKr3QcJYSHHDPlmeYubu4o-d9u706F92dqRN-FFEru87bulDgkpiiTgiC-gUqbc3_L_AUcU90Fiat5nUzxR0kDkAfLZKKD4JNXew"
},
"encryptionKey" : {
"kty" : "RSA",
"x5t#S256" : "URGQh2sd9ypwb2AZSNTFf711rRSDiuTnHw_HhSDB11A",
"e" : "AQAB",
"use" : "enc",
"kid" : "6997314261983703139",
"x5c" : [ "MIICujCCAaKgAwIBAgIIYRt0P3dQMGMwDQYJKoZIhvcNAQELBQAwHTELMAkGA1UEBhMCY2gxDjAMBgNVBAMTBXNpdmVuMB4XDTIyMDcyNDEzMzAzNFoXDTI0MDcyNTEzMzAzNFowHTELMAkGA1UEBhMCY2gxDjAMBgNVBAMTBXNpdmVuMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkzjtMhTSMY58vIZNocx53gGF3v9RQ3MYIa1kzqKSZPpzK8KwkHbo9yb6Wx5i0994G4HCSM9Ea6N4PKiwifRKfy4Ufznb7u/4e03w9QezQVUa6duXhjkwW5trJytoHp5F2Sc95hDTaPfPVlVC5DchjIL+p5Ay1K3lIe+RVPoVYN6CtsLTXJBAhBjtwKQHiKOq3UUbZLzOqMsrCcHXtw6gQHciWua8q4VloKO3sW4LHbeJD4cWy8IKwErtF8ShXo2vSRgeebivRXbA7OTAPEns6E0SoaMLeGdQ83dSHMQKIjY9teHua47Z9ovy5OZ1dXlDBmpKgO9FDiDK76lPYxvc5wIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQA7d7tRXcRme1IoXSfIU0Co36NI4MjB5S37eFNj0ija85nzOrD7PkbaEjTv4pu1R1T2dES/qEXP5CEqarotx625/8sYddy8YRG7emKY47P7wzNJOAOOeAzPw/PR2tYDwdg3QKzG+id8IHeSYTNwMgEpcBM7GIBEwDG9YHRGkCqY46wBJ8H9uFvNGkdzI/VTLoZP4flCf992ImP6ZCUex6MciLwJ9Lq8L7f4wbfvlcy0KhFlAbLztrjstc9g+4e6FyR49ac9STpT/qyYIuyydaGOo01mf66Mncl33emjFLh32qELryOAzVqXiXgBuNSKGO0rFGUAMplnXewG/jP2YEy/" ],
"n" : "kzjtMhTSMY58vIZNocx53gGF3v9RQ3MYIa1kzqKSZPpzK8KwkHbo9yb6Wx5i0994G4HCSM9Ea6N4PKiwifRKfy4Ufznb7u_4e03w9QezQVUa6duXhjkwW5trJytoHp5F2Sc95hDTaPfPVlVC5DchjIL-p5Ay1K3lIe-RVPoVYN6CtsLTXJBAhBjtwKQHiKOq3UUbZLzOqMsrCcHXtw6gQHciWua8q4VloKO3sW4LHbeJD4cWy8IKwErtF8ShXo2vSRgeebivRXbA7OTAPEns6E0SoaMLeGdQ83dSHMQKIjY9teHua47Z9ovy5OZ1dXlDBmpKgO9FDiDK76lPYxvc5w"
},
"username" : "username",
"deviceId" : "Acme Inc Phone. Serial Number Hash: e14c2cec1f8c448a47874b5e164df11727a9e0ad"
}'

Example Response

HTTP/1.1 201 Created
Date: Mon, 25 Jul 2022 11:30:35 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 51

{
"id" : "ee5123bc-3ff1-44c0-b306-783184d9a136"
}

HTTP Status Codes

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

HTTP CodeDescription
201Created The server successfully created the dispatch target.
400Bad Request The provided payload is not properly formatted.
401Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username.
403Forbidden The user is not found in the credential repository based on the provided username.
405Method Not Allowed The method of the received request was not POST.
406Not Acceptable The Accept header is not properly set to application/json.
415Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8.
422Unprocessable Entity The request could not be processed. For example, because the name of the provided dispatch target is already in use by another dispatch target of the user, or because the specified dispatcher is not configured.
500Internal Server Error The server could not process the request because of an unexpected error.

Modify Dispatch Target

This section describes the Modify part of the Dispatch Target Service.

The modify dispatch target HTTP API is particular regarding the approach used to guarantee that the HTTP client is authorized to perform the operation (i.e. to modify the dispatch target). Instead of using authorization headers (containing for instance a SecToken) to do the authorization check, the client must send the payload with a signature. This signature is generated with the private signature key of the dispatch target to be modified. nevisFIDO will only process request that are properly signed. This guarantees that only clients possessing the private signature key of the dispatch target are allowed to modify it. This is the reason why the private signature key is assumed to be safely stored by the HTTP client.

info

The modify dispatch target HTTP API is intended to be used by the Nevis Mobile Authentication SDK only, so it is aimed for mobile applications. Other applications, such as administration web applications, should not use it. It is presented here for reference.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/token/dispatch/targets/{id}

id is the identifier of the dispatch target to be modified.

HTTP Methods

PATCH is the only supported HTTP method.

Request Headers

The following request headers are mandatory:

NameDescription
Content-TypeContent 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 the dispatch target that is being modified.

eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiTXkgTmV3IE1vYmlsZSBQaG9uZSIsInRhcmdldCI6ImJrM1JOd1RlM0gwOkNJMmtfSEh3Z0lwb0RLQ0ladnZETUV4VWRGUTNQMTk4YURQTyJ9.JZPr13S_BLr3_Aw6yqSUpQkiQjXRGuUygwBiCLfhMIUFpVmJXIpu4yc_KF6hQRhPq6Fd6UdVcJLVn9SvplmYWvQLxJQTa0jrSlESP7pW7yfhZOidg8V0E5BRGqtgUTTa5xMv9vC4PG7hjQyAVZPbhsKxpYuHdmZVpaTXJHSfsR3f4EKSQNfHrAKqTtPXInoMVXnHNFb9yRWesoE9yMRfVUhuWGvtZhyDWaZ8di0cRB6i5glHosNXVEA3FtpHK1xCp7DKLoHFbXjwPyBTS1cMalA27wFT5S5kpVOYCEEbI3LlFXLEc9Nl68KOaMOfMQy-38caEzf5rxFYUzJ3fOPtlg

The payload inside the JWS has the following structure:

AttributeTypeDescriptionOptional
nameStringThe new name of the dispatch target. Choose a user-friendly name that helps the user to identify this target. The name must be unique for each dispatch target defined for the user.true
dispatcherStringThe name of the default dispatcher as configured in nevisFIDO that must be associated with this dispatch target. This value corresponds to the value of the type attribute in the nevisFIDO YAML configuration. If the client does not provide the dispatcher to be used in the dispatch token request, this is the dispatcher that will be invoked.true
targetStringThe new information required by the dispatcher to dispatch a token. This information can be a simple identifier (for example, a fcm push identifier or an e-mail address) or more complex data (like a tuple consisting of an e-mail SMTP server and e-mail address). The format of the information depends on the dispatcher implementation. Both JSON and plain text are supported.true
requestIdStringA unique identifier for this JSON payload. It can contain up to 64 characters.true
creationTimeInEpochMillisNumberThe 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.true
signatureKeyStringThe new public key that is used by nevisFIDO to verify the signature of the messages sent by the client to modify the dispatch target. The key must be provided as a JWS object as described in the JSON Web Key (JWK) Format. Either the use or the key_ops attribute must be present. If present, the use attribute of the JWS must be set to sig. If present, the key_ops attribute must contain the value sign.true
encryptionKeyStringThe new public key that is used by nevisFIDO to encrypt the tokens sent to the dispatch target. The key must be provided as a JWS object as described in the JSON Web Key (JWK) Format. Either the use or the key_ops attribute must be present. If present, the use attribute of the JWS must be set to enc. If present, the key_ops attribute must contain the value encrypt.true

Response Headers

The response message has no body. Therefore, no headers will be set in the response either.

Response Body

The body of the response message is empty. Clients must check the returned HTTP status code.

Except, when a potential replay attack is detected. In this case the following payload is returned:

Potential replay attack detected.

If there is a big divergence between the clock of nevisFIDO and the clock of the mobile device, this error can be a false positive. The content of the body can be used in the client side to detect this.

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

Example Request

PATCH /nevisfido/token/dispatch/targets/61cebd35-910a-4100-a659-67a50585eff4 HTTP/1.1
Content-Type: application/jose;charset=UTF-8
Host: fido.siven.ch
Content-Length: 508

eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiTXkgTmV3IE1vYmlsZSBQaG9uZSIsInRhcmdldCI6ImJrM1JOd1RlM0gwOkNJMmtfSEh3Z0lwb0RLQ0ladnZETUV4VWRGUTNQMTk4YURQTyJ9.JZPr13S_BLr3_Aw6yqSUpQkiQjXRGuUygwBiCLfhMIUFpVmJXIpu4yc_KF6hQRhPq6Fd6UdVcJLVn9SvplmYWvQLxJQTa0jrSlESP7pW7yfhZOidg8V0E5BRGqtgUTTa5xMv9vC4PG7hjQyAVZPbhsKxpYuHdmZVpaTXJHSfsR3f4EKSQNfHrAKqTtPXInoMVXnHNFb9yRWesoE9yMRfVUhuWGvtZhyDWaZ8di0cRB6i5glHosNXVEA3FtpHK1xCp7DKLoHFbXjwPyBTS1cMalA27wFT5S5kpVOYCEEbI3LlFXLEc9Nl68KOaMOfMQy-38caEzf5rxFYUzJ3fOPtlg

cURL:

$ curl 'https://fido.siven.ch/nevisfido/token/dispatch/targets/61cebd35-910a-4100-a659-67a50585eff4' -i -X PATCH \
-H 'Content-Type: application/jose;charset=UTF-8' \
-d 'eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiTXkgTmV3IE1vYmlsZSBQaG9uZSIsInRhcmdldCI6ImJrM1JOd1RlM0gwOkNJMmtfSEh3Z0lwb0RLQ0ladnZETUV4VWRGUTNQMTk4YURQTyJ9.JZPr13S_BLr3_Aw6yqSUpQkiQjXRGuUygwBiCLfhMIUFpVmJXIpu4yc_KF6hQRhPq6Fd6UdVcJLVn9SvplmYWvQLxJQTa0jrSlESP7pW7yfhZOidg8V0E5BRGqtgUTTa5xMv9vC4PG7hjQyAVZPbhsKxpYuHdmZVpaTXJHSfsR3f4EKSQNfHrAKqTtPXInoMVXnHNFb9yRWesoE9yMRfVUhuWGvtZhyDWaZ8di0cRB6i5glHosNXVEA3FtpHK1xCp7DKLoHFbXjwPyBTS1cMalA27wFT5S5kpVOYCEEbI3LlFXLEc9Nl68KOaMOfMQy-38caEzf5rxFYUzJ3fOPtlg'

The payload inside the JWS:

{
"name" : "My New Mobile Phone",
"target" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P198aDPO"
}

Example Response

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

HTTP Status Codes

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

HTTP CodeDescription
204No Content The server successfully modified the dispatch target.
400Bad Request The provided payload is not properly formatted.
401Unauthorized The request was not authorized. It was not possible to verify the signature of the request.
404Not Found The provided dispatch target identifier could not be found.
405Method Not Allowed The method of the received request was not PATCH.
415Unsupported Media Type The Content-Type header is not properly set to application/jose;charset=UTF-8.
422Unprocessable 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, or because the specified dispatcher is not configured.
500Internal Server Error The server could not process the request because of an unexpected error.

Delete Dispatch Target

This section describes the Delete part of the Dispatch Target Service. This endpoint is used by

  • Administrators who want to remove dispatch targets of users.
  • Users who cannot access the device holding the private key of the dispatch target and therefore want to remove the dispatch target.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/token/dispatch/targets/{id}

id is the identifier of the dispatch target to be deleted.

HTTP Methods

DELETE is the only supported HTTP method.

Request Headers

There are no mandatory request headers for the Delete Dispatch Target Service.

Request Body

The Delete Dispatch Target Service requires no body. Any provided body will be ignored.

Response Headers

The response message has no body. Therefore, no headers will be set in the response either.

Response Body

The body of the response message is empty. Clients must check the returned HTTP status code.

Example Request

DELETE /nevisfido/token/dispatch/targets/e4d5f49f-9f93-469c-8aa5-d5a81ea46ce5 HTTP/1.1
Host: fido.siven.ch

cURL:

curl 'https://fido.siven.ch/nevisfido/token/dispatch/targets/e4d5f49f-9f93-469c-8aa5-d5a81ea46ce5' -i -X DELETE

Example Response

HTTP/1.1 204 No Content
Date: Mon, 25 Jul 2022 11:30:43 GMT

HTTP Status Codes

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

HTTP CodeDescription
204No Content The server successfully deleted the dispatch target.
400Bad Request The provided payload is not properly formatted.
401Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username.
403Forbidden The request is forbidden. The user does not have the right to delete the specified dispatch target.
404Not Found The provided dispatch target identifier could not be found.
405Method Not Allowed The method of the received request was not DELETE.
415Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8.
500Internal Server Error The server could not process the request because of an unexpected error.

Query Dispatch Target

This section describes the Query part of the Dispatch Target Service. Use this service to retrieve the dispatch targets for a given user.

Base URL

All URLs referenced in this section have the following base:

https://fido.siven.ch/nevisfido/token/dispatch/targets/

HTTP Methods

GET is the only supported HTTP method.

Request Parameters

The following request parameter is mandatory. Provide it in the request URL.

NameDescription
usernameIdentity information of the user whose dispatch targets will be retrieved. In the case of the idm credential repository, the accepted type of username (loginId, email, etc.) depends on how the username mapper of the credential repository is configured.

Request Headers

The following request headers are mandatory:

NameDescription
AcceptAccept header, must be application/json.

Request Body

The Query Dispatch Target Service requires no body. Any provided body will be ignored.

Response Headers

The following response headers will be set:

NameDescription
Content-TypeContent type header, fixed to application/fido+uaf;charset=UTF-8.

Response Body

The body of the response message contains the dispatch targets of the user. The response body is empty if no dispatch targets were found. In this case, an HTTP Not Found (404) status code will be returned.

The table below lists all elements of the response body.

AttributeTypeDescription
dispatchTargetsArrayThe array containing all the dispatch targets for the provided user name.
dispatchTargets[].idStringThe identifier of the dispatch target. This identifier is immutable and must be used by the client to update and delete the dispatch target. It must also be used to select the dispatch target to which the generated tokens must be sent. This identifier is to be used by nevisFIDO and its format is not related to the type of the dispatcher.
dispatchTargets[].nameStringThe name describing the dispatch target. It can be used as a user-friendly representation that helps the end-user to identify this target. It must be unique for all the dispatch targets defined for the user.
dispatchTargets[].dispatcherStringThe name of the [Dispatcher] as configured in nevisFIDO. This value corresponds to the value of the type attribute in the nevisFIDO YAML configuration. The dispatcher attribute has been deprecated in the dispatch target. This attribute will not be returned by the Query Dispatch Target Service in future releases.

Example Request

GET /nevisfido/token/dispatch/targets?username=username HTTP/1.1
Accept: application/json
Host: fido.siven.ch

cURL:

$ curl 'https://fido.siven.ch/nevisfido/token/dispatch/targets?username=username' -i -X GET \
-H 'Accept: application/json'

Example Response

HTTP/1.1 200 OK
Date: Mon, 25 Jul 2022 11:30:35 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Content-Length: 117

{
"dispatchTargets" : [ {
"id" : "b4ad2a81-5a88-413d-885f-6a1781dbf5a3",
"name" : "My Mobile Phone"
} ]
}

HTTP Status Codes

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

HTTP CodeDescription
200OK The server retrieved dispatch targets for the user.
400Bad Request The provided payload is not properly formatted.
401Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username.
404Not Found No dispatch target could be found.
405Method Not Allowed The method of the received request was not GET.
406Not Acceptable The Accept header is not properly set to application/json.
415Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8.
500Internal Server Error The server could not process the request because of an unexpected error.