> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/key-components/authenticators/web-authenticator-api.md).

# Web Authenticator API

Configuration and usage guidance for Web Authenticator API in Fortified ID Access.

## 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.

{% tabs %}
{% tab title="Propertiesl" %}

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code>success</code></td><td><a href="#message-status">Message status</a> flag indicating success (<code>true</code>) or failure (<code>false</code>). Only used in response messages.</td></tr><tr><td><code>reason</code></td><td>Error reason. Only supplied for non successful (failed) messages/responses.</td></tr><tr><td><code>type</code></td><td>Message type. Used for routing, authenticators registers handlers for each message type they support.</td></tr><tr><td><code>reply_to</code></td><td>Reply address</td></tr><tr><td><code>data</code></td><td>Custom message data object. May contain arbitrary data of JSON format.</td></tr><tr><td><code>data.message</code></td><td>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 <code>"failure",</code> 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.</td></tr><tr><td><code>data.message.text</code></td><td>Message text or a translation key.</td></tr><tr><td><code>data.location</code></td><td>Redirect location. If a location is supplied, the view MUST redirect to this location. Always supplied in responses of type <code>"complete"</code>, MAY be supplied in any response.</td></tr></tbody></table>
{% endtab %}

{% tab title="Request" %}

```json
{
    "type": "<message-type>",
    "data": {
    
    }
}
```

{% endtab %}

{% tab title="Response (success)" %}

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

{% endtab %}

{% tab title="Response (failure)" %}

```json
{
    "success": false,
    "reason": "Error reason message",
    "data": {
    
    }
}
```

{% endtab %}
{% endtabs %}

## 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.

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Request" %}
Requests of type `"complete"` are not allowed.
{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}

#### 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.

{% tabs %}
{% tab title="Request" %}
Requests of type `"failure"` are not allowed.
{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fortifiedid.se/access/key-components/authenticators/web-authenticator-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.