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:
| Name | Description |
|---|---|
Accept | Accept header, must be application/json. |
Content-Type | Content type header, must be application/json. |
Request Body
The Create Dispatch Target Service requires a JSON payload with the following structure:
| Attribute | Type | Description | Optional |
|---|---|---|---|
name | String | The 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 |
deviceId | String | The 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 |
dispatcher | String | The 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 |
target | String | The 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 |
signatureKey | Object | The 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 |
encryptionKey | Object | The 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 |
username | String | Identity 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:
| Name | Description |
|---|---|
Content-Type | Content 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.
| Attribute | Type | Description |
|---|---|---|
id | String | The 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 Code | Description |
|---|---|
| 201 | Created The server successfully created the dispatch target. |
| 400 | Bad Request The provided payload is not properly formatted. |
| 401 | Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username. |
| 403 | Forbidden The user is not found in the credential repository based on the provided username. |
| 405 | Method Not Allowed The method of the received request was not POST. |
| 406 | Not Acceptable The Accept header is not properly set to application/json. |
| 415 | Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8. |
| 422 | Unprocessable 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. |
| 500 | Internal 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 (s aontaining notably a SecToken) to do the authorization check, the client must send the payload with a signature. Thes aignature 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 dispath 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.
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:
| 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 the dispatch target that is being modified.
eyJraWQiOiJjZXJ0QWxpYXMiLCJhbGciOiJSUzI1NiJ9.eyJuYW1lIjoiTXkgTmV3IE1vYmlsZSBQaG9uZSIsInRhcmdldCI6ImJrM1JOd1RlM0gwOkNJMmtfSEh3Z0lwb0RLQ0ladnZETUV4VWRGUTNQMTk4YURQTyJ9.JZPr13S_BLr3_Aw6yqSUpQkiQjXRGuUygwBiCLfhMIUFpVmJXIpu4yc_KF6hQRhPq6Fd6UdVcJLVn9SvplmYWvQLxJQTa0jrSlESP7pW7yfhZOidg8V0E5BRGqtgUTTa5xMv9vC4PG7hjQyAVZPbhsKxpYuHdmZVpaTXJHSfsR3f4EKSQNfHrAKqTtPXInoMVXnHNFb9yRWesoE9yMRfVUhuWGvtZhyDWaZ8di0cRB6i5glHosNXVEA3FtpHK1xCp7DKLoHFbXjwPyBTS1cMalA27wFT5S5kpVOYCEEbI3LlFXLEc9Nl68KOaMOfMQy-38caEzf5rxFYUzJ3fOPtlg
The payload inside the JWS has the following structure:
| Attribute | Type | Description | Optional |
|---|---|---|---|
name | String | The 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 |
dispatcher | String | The 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 |
target | String | The 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 |
signatureKey | String | The new public key. nevisFIDO uses this key 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 |
encryptionKey | String | The 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.
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 Code | Description |
|---|---|
| 204 | No Content The server successfully modified the dispatch target. |
| 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. |
| 404 | Not Found The provided dispatch target identifier could not be found. |
| 405 | Method Not Allowed The method of the received request was not PATCH. |
| 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, or because the specified dispatcher is not configured. |
| 500 | Internal 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 Code | Description |
|---|---|
| 204 | No Content The server successfully deleted the dispatch target. |
| 400 | Bad Request The provided payload is not properly formatted. |
| 401 | Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username. |
| 403 | Forbidden The request is forbidden. The user does not have the right to delete the specified dispatch target. |
| 404 | Not Found The provided dispatch target identifier could not be found. |
| 405 | Method Not Allowed The method of the received request was not DELETE. |
| 415 | Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8. |
| 500 | Internal 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.
| Name | Description |
|---|---|
username | Identity 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:
| Name | Description |
|---|---|
Accept | Accept 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:
| Name | Description |
|---|---|
Content-Type | Content 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.
| Attribute | Type | Description |
|---|---|---|
dispatchTargets | Array | The array containing all the dispatch targets for the provided user name. |
dispatchTargets[].id | String | The 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[].name | String | The 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[].dispatcher | String | The 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 Code | Description |
|---|---|
| 200 | OK The server retrieved dispatch targets for the user. |
| 400 | Bad Request The provided payload is not properly formatted. |
| 401 | Unauthorized The request was not authorized. There is an invalid SecToken or unresolved username. |
| 404 | Not Found No dispatch target could be found. |
| 405 | Method Not Allowed The method of the received request was not GET. |
| 406 | Not Acceptable The Accept header is not properly set to application/json. |
| 415 | Unsupported Media Type The Content-Type header is not properly set to application/json;charset=UTF-8. |
| 500 | Internal Server Error The server could not process the request because of an unexpected error. |