Captive Portal API
RFC 8908

Document Type RFC - Proposed Standard (September 2020; No errata)
Authors Tommy Pauly  , Darshak Thakore 
Last updated 2020-09-21
Stream Internet Engineering Task Force (IETF)
Formats plain text html xml pdf htmlized (tools) htmlized bibtex
Stream WG state Submitted to IESG for Publication
Document shepherd Martin Thomson
Shepherd write-up Show (last changed 2020-04-20)
IESG IESG state RFC 8908 (Proposed Standard)
Action Holders
Consensus Boilerplate Yes
Telechat date
Responsible AD Barry Leiba
Send notices to Martin Thomson <>
IANA IANA review state Version Changed - Review Needed
IANA action state RFC-Ed-Ack

Internet Engineering Task Force (IETF)                     T. Pauly, Ed.
Request for Comments: 8908                                    Apple Inc.
Category: Standards Track                                D. Thakore, Ed.
ISSN: 2070-1721                                                CableLabs
                                                          September 2020

                           Captive Portal API


   This document describes an HTTP API that allows clients to interact
   with a Captive Portal system.  With this API, clients can discover
   how to get out of captivity and fetch state about their Captive
   Portal sessions.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at

Copyright Notice

   Copyright (c) 2020 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   ( in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction
   2.  Terminology
   3.  Workflow
   4.  API Connection Details
     4.1.  Server Authentication
   5.  API State Structure
   6.  Example Interaction
   7.  Security Considerations
     7.1.  Privacy Considerations
   8.  IANA Considerations
     8.1.  Captive Portal API JSON Media Type Registration
     8.2.  Captive Portal API Keys Registry
   9.  References
     9.1.  Normative References
     9.2.  Informative References
   Authors' Addresses

1.  Introduction

   This document describes a HyperText Transfer Protocol (HTTP)
   Application Programming Interface (API) that allows clients to
   interact with a Captive Portal system.  The API defined in this
   document has been designed to meet the requirements in the Captive
   Portal Architecture [CAPPORT-ARCH].  Specifically, the API provides:

   *  The state of captivity (whether or not the client has access to
      the Internet).

   *  A URI of a user-facing web portal that can be used to get out of

   *  Authenticated and encrypted connections, using TLS for connections
      to both the API and user-facing web portal.

2.  Terminology

   This document leverages the terminology and components described in
   [CAPPORT-ARCH] and additionally defines the following terms:

   Captive Portal Client
      The client that interacts with the Captive Portal API is typically
      some application running on the user equipment that is connected
      to the captive network.  This is also referred to as the "client"
      in this document.

   Captive Portal API Server
      The server exposing the APIs defined in this document to the
      client.  This is also referred to as the "API server" in this

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

3.  Workflow

   The Captive Portal Architecture defines several categories of
   interaction between clients and Captive Portal systems:

   1.  Provisioning, in which a client discovers that a network has a
       captive portal and learns the URI of the API server.

   2.  API Server interaction, in which a client queries the state of
       captivity and retrieves the necessary information to get out of

   3.  Enforcement, in which the enforcement device in the network
       blocks disallowed traffic.

   This document defines the mechanisms used in the second category.  It
   is assumed that the location of the Captive Portal API server has
   been discovered by the client as part of provisioning.  A set of
   mechanisms for discovering the API server endpoint is defined in

4.  API Connection Details

   The API server endpoint MUST be accessed over HTTP using an https URI
   [RFC2818] and SHOULD use the default https port.  For example, if the
Show full document text