Skip to main content
Version: 1.15.x.x LTS

HTTP APIs and Client Authentication


This section describes a generic process of using FIDO authentication for protection and to authenticate against HTTP APIs. This process relies heavily on the nevisProxy and nevisAuth configuration, which must fit exactly or the outlined process will not work as described. The aim of the process is to simplify HTTP API authentication for HTTP clients having to interact with NEVIS.

The setup described in this chapter allows you to:

  1. Provide a single endpoint URL for HTTP clients to authenticate against.
  2. Protect HTTP APIs that require authorisation with FIDO UAF authentication.
  3. Respond with HTTP status code 401 to all endpoint calls without authorisation credentials provided by the HTTP client.
  4. Allow certain HTTP methods to bypass the authorisation. For example, the HTTP PATCH method does not require authentication, whereas the HTTP DELETE method does.


HTTP API client authentication flow


External URLRequest Content TypenevisFIDO URLNotes
/auth/fidouafapplication/json; charset=UTF-8-This endpoint always redirects to nevisAuth and will result in an AuthenticationRequest sent back to the client.
/auth/authenticationresponseapplication/fido+uaf;charset=UTF-8/nevisfido/uaf/1.1/authenticationThis endpoint is used to send AuthenticationResponse objects from the client back to nevisFIDO.


The following table describes the steps of the HTTP API client authentication flow. The numbers in the table correspond with the numbers of the steps in the above figure Mappings of external URLs to nevisFIDO URLs.

Step nr.DescriptionEndpointPayloadNotes
1The NEVIS client initiates the authentication by sending the user-to-be-authenticated to the defined "mobile authentication" endpoint URL./auth/fidouafapplication/json; charset=UTF-8 {"username":"<user to authenticate">See the required configuration for nevisProxy and nevisAuth.
2NEVIS answers with 200 "OK".-A JSON containing the AuthenticationRequest (for details, see the chapter "Authentication Response Service" of the nevisFIDO Reference Guide).The client must extract the fidoUafSessionId from the session ID extension sent in the AuthenticationRequest. This ID is needed for subsequent requests.
3The client sends the AuthenticationResponse via HTTP POST./auth/authenticationresponseA JSON containing the AuthenticationResponse (for details, see chapter "Authentication Response Service - Request Body" of the nevisFIDO Reference Guide).
4NEVIS answers with 200 "OK".-A JSON containing the StatusResponse (for details, see chapter "Authentication Response Service - Response Body" of the nevisFIDO Reference Guide).NEVIS answers with the StatusResponse.The client must evaluate the response to ensure that the statusCode indicates a successful FIDO UAF operation (1200 "OK").
5The client sends the fidoUafSessionId via HTTP POST./auth/fidouafapplication/json; charset=UTF-8 {"fidoUafSessionId":"<sessionId>"}The client sends the previously obtained session ID to NEVIS to continue the authentication process.
6NEVIS answers with 200 "OK".-A JSON containing the StatusResponse (for details, see chapter "Status Service - Response Body"of the nevisFIDO Reference Guide)NEVIS answers with the current authentication status as described in the nevisFIDO Reference Guide.The client must evaluate the response to ensure that the status attribute indicates a non-failure.If the value of the status attribute is not "succeeded", the client needs to re-send the request after a client-defined period.
7The client sends the fidoUafSessionId via HTTP POST./auth/fidouafapplication/json; charset=UTF-8 {"fidoUafSessionId":"<sessionId>"}If the last call returned "succeeded", the client needs to send a final request to establish the authenticated session.
8NEVIS answers with 200 "OK" or 401 ("unauthorized").-application/json; charset=UTF-8, Cookie {"status":"completed"}NEVIS answers with a final response and the cookie.For the response payload, see the required configuration for the nevisAuth "AuthDone" state.The Nevis Authentication Cloud will answer with a JWT token instead of a cookie.

The current flow results in a returned cookie, which is bound to an authenticated user session. This is the expected behavior for the on-premise product. The Nevis Authentication Cloud uses JWT tokens.


For implementation details such as NEVIS component configuration snippets, refer to Use Cases and Best Practices.


When returning an HTTP 401 status response, the client does not need any additional headers. This is because the FIDO authentication is the only kind of authentication currently supported by the client.

Use the DirectResponseAuthState for the implementation of this feature. For more information, see the example snippets for In-Band Authentication.