Web Authenticator API

Introduction

The Web Authenticator API is the interface between authenticator implementations (server) and their views (user agent/browser) and is based on HTTP and JSON.

HTTP requirements

All API request MUST use HTTP method PUT.

User agent MUST support/allow cookies.

Message format

WAAPI uses a standardised format for API messages. It's an enveloped JSON format with common headers and custom data.

Propertiesl

Name	Description
success	Message status flag indicating success (true) or failure (false). Only used in response messages.
reason	Error reason. Only supplied for non successful (failed) messages/responses.
type	Message type. Used for routing, authenticators registers handlers for each message type they support.
reply_to	Reply address
data	Custom message data object. May contain arbitrary data of JSON format.
data.message	Response message object. If a message is supplied it should be translated and displayed to the end user. If both message and location is supplied, message is first displayed and when confirmed redirection is performed. Commonly used in messages of type "failure", but MAY be supplied in any response. When supplied in a failure context it should be considered an error message, in regular messages as information.
data.message.text	Message text or a translation key.
data.location	Redirect location. If a location is supplied, the view MUST redirect to this location. Always supplied in responses of type "complete", MAY be supplied in any response.

Request

{
    "type": "<message-type>",
    "data": {

    }
}

Response (success)

{
    "success": true,
    "type": "<message-type>",
    "data": {

    }
}

Response (failure)

{
    "success": false,
    "reason": "Error reason message",
    "data": {

    }
}

Protocol

Each authenticator defines it own protocol when is comes to which messages to support and what messages should contain. This is documented on respective authenticator.

Message status

The status of a message represent the result of the operation returning the message.

If the operation succeeded without errors, "success": true is returned.

If the operation failed, "success": false is returned.

Each authenticators define what is considered to be a failure and not. If an error is a part of the normal operation (for example invalid user input) it is perfectly valid to return a failure message (i.e. a message with "type": "failure") with status "success": true containing an error message. In this case the message object in data should be used, not the reason header which is only allowed in combination with "success": false.

Common messages

Cancel

Use this message to cancel the operation(s) of the current authenticator. If successful, authenticator replies with a redirect location to where the view MUST redirect.

Request

{
    "type": "cancel",
    "data": {
    }
}

Response

{
    "success": "true",
    "type": "cancel",
    "data": {
        "location": "/path/to/cancel/location"
    }
}

Complete

This response message means that the authentication process for the current authenticator is completed and can be . This message always contain a redirect location to where the view MUST redirect.

Request

Requests of type "complete" are not allowed.

Response

{
    "success": "true",
    "type": "complete",
    "data": {
        "location": "/path/to/next/step"
    }
}

Failure

When a failure occurs a failure response is returned. This message SHOULD contain a message which MUST be displayed to the user. Message MAY contain a location for redirect, which the user agent MUST follow. If both message and location is supplied, message MUST first be displayed and when confirmed, redirect is performed.

Request

Requests of type "failure" are not allowed.

Response

{
    "success": "true",
    "type": "failure",
    "data": {
        "message": {
            "text": "Process cancelled"
        },
        "location": "/path/to/next/step"
    }
}