.. index:: single: http_authenticate .. _http_authenticate/0:

.. rst-class:: right

object

http_authenticate

HTTP Basic authentication parsing, generation, challenge building, and request verification helpers.

| Availability: | logtalk_load(http_authenticate(loader))

| Author: Paulo Moura | Version: 1:0:0 | Date: 2026-06-26

| Compilation flags: | static, context_switching_calls

| Imports: | public :ref:`options <options/0>` | public :ref:`http_text_helpers <http_text_helpers/0>` | Uses: | :ref:`base64 <base64/0>` | :ref:`http_core <http_core/0>` | :ref:`list <list/0>` | :ref:`type <type/0>` | :ref:`user <user/0>`

| Remarks: | (none)

| Inherited public predicates: |  :ref:options_protocol/0::check_option/1  :ref:options_protocol/0::check_options/1  :ref:options_protocol/0::default_option/1  :ref:options_protocol/0::default_options/1  :ref:options_protocol/0::option/2  :ref:options_protocol/0::option/3  :ref:options_protocol/0::valid_option/1  :ref:options_protocol/0::valid_options/1  

.. contents:: :local: :backlinks: top

Public predicates

.. index:: challenge/2 .. _http_authenticate/0::challenge/2:

challenge/2 ^^^^^^^^^^^^^^^

Returns the single parsed Basic WWW-Authenticate challenge from a normalized HTTP response when present.

| Compilation flags: | static

| Template: | challenge(Response,Challenge) | Mode and number of proofs: | challenge(+compound,-compound) - zero_or_one

---

.. index:: authorization/2 .. _http_authenticate/0::authorization/2:

authorization/2 ^^^^^^^^^^^^^^^^^^^

Returns the single parsed Basic Authorization header from a normalized HTTP request when present.

| Compilation flags: | static

| Template: | authorization(Request,Authorization) | Mode and number of proofs: | authorization(+compound,-compound) - zero_or_one

---

.. index:: parse_challenge/2 .. _http_authenticate/0::parse_challenge/2:

parse_challenge/2 ^^^^^^^^^^^^^^^^^^^^^

Parses one Basic challenge header field value into a normalized basic_challenge/1 term.

| Compilation flags: | static

| Template: | parse_challenge(Text,Challenge) | Mode and number of proofs: | parse_challenge(++text,-compound) - one_or_error

| Exceptions: | Text is not a valid Basic challenge header value: | domain_error(http_authenticate_header(www_authenticate),invalid(syntax)) | Text uses an unsupported authentication scheme: | domain_error(http_authenticate_header(www_authenticate),unsupported_scheme(Scheme)) | Text contains a duplicated Basic challenge directive: | domain_error(http_authenticate_header(www_authenticate),duplicate(Name)) | Text is missing a required Basic challenge directive: | domain_error(http_authenticate_header(www_authenticate),missing(Name)) | Text contains an unexpected Basic challenge directive: | domain_error(http_authenticate_header(www_authenticate),unexpected(Name)) | Text contains an invalid Basic challenge charset: | domain_error(http_authenticate_header(www_authenticate),invalid(charset))

---

.. index:: generate_challenge/2 .. _http_authenticate/0::generate_challenge/2:

generate_challenge/2 ^^^^^^^^^^^^^^^^^^^^^^^^

Generates one canonical Basic challenge header field value from a normalized basic_challenge/1 term.

| Compilation flags: | static

| Template: | generate_challenge(Challenge,HeaderValue) | Mode and number of proofs: | generate_challenge(+compound,-atom) - one_or_error

| Exceptions: | Challenge is not a valid normalized Basic challenge term: | domain_error(http_authenticate_term(challenge),Challenge) | Challenge is missing a required field: | domain_error(http_authenticate_term(challenge),missing(Name)) | Challenge contains a duplicated field: | domain_error(http_authenticate_term(challenge),duplicate(Name)) | Challenge contains an unexpected field: | domain_error(http_authenticate_term(challenge),unexpected(Name)) | Challenge contains an invalid field: | domain_error(http_authenticate_term(challenge),invalid(Field))

---

.. index:: parse_authorization/2 .. _http_authenticate/0::parse_authorization/2:

parse_authorization/2 ^^^^^^^^^^^^^^^^^^^^^^^^^

Parses one Basic authorization header field value into a normalized basic_authorization/1 term.

| Compilation flags: | static

| Template: | parse_authorization(Text,Authorization) | Mode and number of proofs: | parse_authorization(++text,-compound) - one_or_error

| Exceptions: | Text is not a valid Basic authorization header value: | domain_error(http_authenticate_header(authorization),invalid(syntax)) | Text uses an unsupported authentication scheme: | domain_error(http_authenticate_header(authorization),unsupported_scheme(Scheme)) | Text contains invalid Basic credentials: | domain_error(http_authenticate_header(authorization),invalid(credentials))

---

.. index:: generate_authorization/2 .. _http_authenticate/0::generate_authorization/2:

generate_authorization/2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generates one canonical Basic authorization header field value from a normalized basic_authorization/1 term.

| Compilation flags: | static

| Template: | generate_authorization(Authorization,HeaderValue) | Mode and number of proofs: | generate_authorization(+compound,-atom) - one_or_error

| Exceptions: | Authorization is not a valid normalized Basic authorization term: | domain_error(http_authenticate_term(authorization),Authorization) | Authorization contains an invalid Basic username: | domain_error(http_authenticate_value(username),Username)

---

.. index:: protect_request/4 .. _http_authenticate/0::protect_request/4:

protect_request/4 ^^^^^^^^^^^^^^^^^^^^^

Verifies a normalized HTTP request using a Basic verifier object and returns either continue(Request) or respond(Response).

| Compilation flags: | static

| Template: | protect_request(Request,Verifier,Action,Options) | Mode and number of proofs: | protect_request(+compound,+object_identifier,-compound,+list(compound)) - one_or_error

| Exceptions: | Request is not a valid normalized HTTP request term: | domain_error(http_request,Request) | Verifier is a variable: | instantiation_error | Verifier is neither a variable nor an existing object: | existence_error(http_authenticate_verifier,Verifier) | Verifier does not implement the Basic verifier protocol: | domain_error(http_authenticate_verifier,Verifier) | Options is a variable or a partial list: | instantiation_error | Options is neither a variable nor a list: | type_error(list,Options) | An element Option of the list Options is neither a variable nor a compound term: | type_error(compound,Option) | An element Option of the list Options is a compound term but not a valid option: | domain_error(option,Option) | Options contains an invalid Basic-auth status: | domain_error(http_authenticate_status,Status) | Options contains invalid Basic-auth headers: | domain_error(http_headers,Headers) | Options contains an invalid Basic-auth body: | domain_error(http_body,Body) | Options contains invalid Basic-auth properties: | domain_error(http_properties,Properties)

---

.. index:: unauthorized_response/3 .. _http_authenticate/0::unauthorized_response/3:

unauthorized_response/3 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Builds a normalized 401 Unauthorized response and returns the generated normalized Basic challenge term.

| Compilation flags: | static

| Template: | unauthorized_response(Challenge,Response,Options) | Mode and number of proofs: | unauthorized_response(-compound,-compound,+list(compound)) - one_or_error

| Exceptions: | Options is a variable or a partial list: | instantiation_error | Options is neither a variable nor a list: | type_error(list,Options) | An element Option of the list Options is neither a variable nor a compound term: | type_error(compound,Option) | An element Option of the list Options is a compound term but not a valid option: | domain_error(option,Option) | Options contains an invalid Basic-auth status: | domain_error(http_authenticate_status,Status) | Options contains invalid Basic-auth headers: | domain_error(http_headers,Headers) | Options contains an invalid Basic-auth body: | domain_error(http_body,Body) | Options contains invalid Basic-auth properties: | domain_error(http_properties,Properties) | The generated response headers violate normalized HTTP response semantics: | domain_error(http_header_semantics,Header) | The generated response properties violate normalized HTTP response semantics: | domain_error(http_property_semantics,Property)

---

.. index:: unauthorized_response/4 .. _http_authenticate/0::unauthorized_response/4:

unauthorized_response/4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Decorates a normalized HTTP response with an explicit normalized Basic challenge term and returns the resulting 401 Unauthorized response.

| Compilation flags: | static

| Template: | unauthorized_response(Challenge,Response0,Response,Options) | Mode and number of proofs: | unauthorized_response(+compound,+compound,-compound,+list(compound)) - one_or_error

| Exceptions: | Challenge is not a valid normalized Basic challenge term: | domain_error(http_authenticate_term(challenge),Challenge) | Response0 is not a valid normalized HTTP response term: | domain_error(http_response,Response0) | Options is a variable or a partial list: | instantiation_error | Options is neither a variable nor a list: | type_error(list,Options) | An element Option of the list Options is neither a variable nor a compound term: | type_error(compound,Option) | An element Option of the list Options is a compound term but not a valid unauthorized-response overlay option: | domain_error(http_authenticate_unauthorized_response_overlay_option,Option) | Options contains an invalid Basic-auth status: | domain_error(http_authenticate_status,Status) | Options contains invalid Basic-auth headers: | domain_error(http_headers,Headers) | Options contains an invalid Basic-auth body: | domain_error(http_body,Body) | Options contains invalid Basic-auth properties: | domain_error(http_properties,Properties) | The decorated response headers violate normalized HTTP response semantics: | domain_error(http_header_semantics,Header) | The decorated response properties violate normalized HTTP response semantics: | domain_error(http_property_semantics,Property)

---

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

(no local declarations; see entity ancestors if any)

Operators

(none)