.. index:: single: http_oauth
.. _http_oauth/0:

.. rst-class:: right

**object**

``http_oauth``
==============

OAuth Bearer parsing, challenge, authentication, authorization, and response helpers.

| **Availability:** 
|    ``logtalk_load(http_oauth(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-09-01

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`options <options/0>`
|    ``public`` :ref:`http_oauth_helpers <http_oauth_helpers/0>`
| **Uses:**
|    :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_oauth/0::challenge/2:

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

Returns the single parsed Bearer challenge from a normalized HTTP response. Fails when the response contains no Bearer ``WWW-Authenticate`` header field.

| **Compilation flags:**
|    ``static``

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

| **Exceptions:**
|    ``Response`` is not a valid normalized HTTP response term:
|        ``domain_error(http_response,Response)``
|    ``Response`` contains multiple Bearer ``WWW-Authenticate`` header values ``Values``:
|        ``domain_error(http_oauth_header_values(www_authenticate),Values)``
|    A Bearer ``WWW-Authenticate`` header field uses unsupported authentication scheme ``Scheme``:
|        ``domain_error(http_oauth_bearer_scheme,Scheme)``
|    A Bearer ``WWW-Authenticate`` header field value ``Value`` has invalid syntax:
|        ``domain_error(http_oauth_header(www_authenticate),Value)``
|    A Bearer ``WWW-Authenticate`` header field value ``Value`` contains invalid or duplicate parameters:
|        ``domain_error(http_oauth_challenge_parameters,Value)``
|    A Bearer ``WWW-Authenticate`` header field contains invalid scope value ``Scope``:
|        ``domain_error(http_oauth_scope,Scope)``
|    A Bearer ``WWW-Authenticate`` header field contains invalid parameter name ``Name``:
|        ``domain_error(http_authentication_parameter_name,Name)``


------------

.. index:: authorization/2
.. _http_oauth/0::authorization/2:

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

Returns the single parsed Bearer authorization from a normalized HTTP request. Fails when the request contains no Bearer ``Authorization`` header field.

| **Compilation flags:**
|    ``static``

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

| **Exceptions:**
|    ``Request`` is not a valid normalized HTTP request term:
|        ``domain_error(http_request,Request)``
|    ``Request`` contains multiple Bearer ``Authorization`` header values ``Values``:
|        ``domain_error(http_oauth_header_values(authorization),Values)``
|    A Bearer ``Authorization`` header field uses unsupported authentication scheme ``Scheme``:
|        ``domain_error(http_oauth_bearer_scheme,Scheme)``
|    A Bearer ``Authorization`` header field value ``Value`` has invalid syntax:
|        ``domain_error(http_oauth_header(authorization),Value)``
|    A Bearer ``Authorization`` header field contains invalid token ``Token``:
|        ``domain_error(http_oauth_bearer_token,Token)``


------------

.. index:: parse_challenge/2
.. _http_oauth/0::parse_challenge/2:

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

Parses a Bearer challenge header value.

| **Compilation flags:**
|    ``static``

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

| **Exceptions:**
|    ``Text`` is a variable:
|        ``instantiation_error``
|    ``Text`` is neither a variable nor text:
|        ``type_error(text,Text)``
|    ``Text`` uses unsupported authentication scheme ``Scheme``:
|        ``domain_error(http_oauth_bearer_scheme,Scheme)``
|    ``Text`` is not a valid Bearer challenge header value:
|        ``domain_error(http_oauth_header(www_authenticate),Text)``
|    ``Text`` contains invalid or duplicate Bearer challenge parameters:
|        ``domain_error(http_oauth_challenge_parameters,Text)``
|    ``Text`` contains invalid Bearer scope value ``Scope``:
|        ``domain_error(http_oauth_scope,Scope)``
|    ``Text`` contains invalid Bearer challenge parameter name ``Name``:
|        ``domain_error(http_authentication_parameter_name,Name)``


------------

.. index:: generate_challenge/2
.. _http_oauth/0::generate_challenge/2:

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

Generates a Bearer challenge header value.

| **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 Bearer challenge term or contains duplicate fields:
|        ``domain_error(http_oauth_term(challenge),Challenge)``


------------

.. index:: parse_authorization/2
.. _http_oauth/0::parse_authorization/2:

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

Parses a Bearer authorization header value.

| **Compilation flags:**
|    ``static``

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

| **Exceptions:**
|    ``Text`` is a variable:
|        ``instantiation_error``
|    ``Text`` is neither a variable nor text:
|        ``type_error(text,Text)``
|    ``Text`` uses unsupported authentication scheme ``Scheme``:
|        ``domain_error(http_oauth_bearer_scheme,Scheme)``
|    ``Text`` is not a valid Bearer authorization header value:
|        ``domain_error(http_oauth_header(authorization),Text)``
|    ``Text`` contains invalid Bearer token ``Token``:
|        ``domain_error(http_oauth_bearer_token,Token)``


------------

.. index:: generate_authorization/2
.. _http_oauth/0::generate_authorization/2:

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

Generates a Bearer authorization header value.

| **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 Bearer authorization term:
|        ``domain_error(http_oauth_term(authorization),Authorization)``


------------

.. index:: authenticate_request/4
.. _http_oauth/0::authenticate_request/4:

``authenticate_request/4``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Authenticates a normalized request, returning continue(AnnotatedRequest) or respond(Response).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``authenticate_request(Request,Verifier,Action,Options)``
| **Mode and number of proofs:**
|    ``authenticate_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`` does not name an existing object:
|        ``existence_error(http_oauth_verifier,Verifier)``
|    ``Verifier`` does not implement ``http_oauth_verifier_protocol``:
|        ``domain_error(http_oauth_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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    ``Options`` omits a protected-resource identifier:
|        ``domain_error(http_oauth_protection_options,Options)``
|    ``Verifier`` returns malformed normalized token information ``TokenInfo``:
|        ``domain_error(http_oauth_token_info,TokenInfo)``
|    The generated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The generated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The generated response property ``Property`` violates normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: authorize_request/3
.. _http_oauth/0::authorize_request/3:

``authorize_request/3``
^^^^^^^^^^^^^^^^^^^^^^^

Authorizes an authenticated request against required scopes, returning continue(Request) or respond(Response).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``authorize_request(Request,Action,Options)``
| **Mode and number of proofs:**
|    ``authorize_request(+compound,--compound,+list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Request`` is not a valid normalized HTTP request term:
|        ``domain_error(http_request,Request)``
|    ``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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    ``Request`` is not annotated with authenticated OAuth scopes:
|        ``domain_error(http_oauth_authenticated_request,Request)``
|    The generated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The generated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The generated response property ``Property`` violates normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: protect_request/4
.. _http_oauth/0::protect_request/4:

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

Authenticates and authorizes a normalized request.

| **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`` does not name an existing object:
|        ``existence_error(http_oauth_verifier,Verifier)``
|    ``Verifier`` does not implement ``http_oauth_verifier_protocol``:
|        ``domain_error(http_oauth_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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    ``Options`` omits a protected-resource identifier:
|        ``domain_error(http_oauth_protection_options,Options)``
|    ``Verifier`` returns malformed normalized token information ``TokenInfo``:
|        ``domain_error(http_oauth_token_info,TokenInfo)``
|    The generated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The generated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The generated response property ``Property`` violates normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: token_info/2
.. _http_oauth/0::token_info/2:

``token_info/2``
^^^^^^^^^^^^^^^^

Returns normalized OAuth token information from an authenticated request.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``token_info(Request,TokenInfo)``
| **Mode and number of proofs:**
|    ``token_info(+compound,-compound)`` - ``zero_or_one``


------------

.. index:: scopes/2
.. _http_oauth/0::scopes/2:

``scopes/2``
^^^^^^^^^^^^

Returns granted OAuth scopes from an authenticated request.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``scopes(Request,Scopes)``
| **Mode and number of proofs:**
|    ``scopes(+compound,-list(atom))`` - ``zero_or_one``


------------

.. index:: unauthorized_response/3
.. _http_oauth/0::unauthorized_response/3:

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

Builds a normalized 401 response and its Bearer challenge.

| **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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    The generated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The generated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The generated response property ``Property`` violates normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: unauthorized_response/4
.. _http_oauth/0::unauthorized_response/4:

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

Decorates a normalized response as a 401 Bearer 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 Bearer challenge term or contains duplicate fields:
|        ``domain_error(http_oauth_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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    The decorated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The decorated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The decorated response property ``Property`` violates normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: forbidden_response/3
.. _http_oauth/0::forbidden_response/3:

``forbidden_response/3``
^^^^^^^^^^^^^^^^^^^^^^^^

Builds a normalized 403 response and its Bearer challenge.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``forbidden_response(Challenge,Response,Options)``
| **Mode and number of proofs:**
|    ``forbidden_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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    The generated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The generated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The generated response property ``Property`` violates normalized HTTP response semantics:
|        ``domain_error(http_property_semantics,Property)``


------------

.. index:: forbidden_response/4
.. _http_oauth/0::forbidden_response/4:

``forbidden_response/4``
^^^^^^^^^^^^^^^^^^^^^^^^

Decorates a normalized response as a 403 Bearer response.

| **Compilation flags:**
|    ``static``

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

| **Exceptions:**
|    ``Challenge`` is not a valid normalized Bearer challenge term or contains duplicate fields:
|        ``domain_error(http_oauth_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 a variable:
|        ``instantiation_error``
|    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)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not name an existing object:
|        ``existence_error(http_oauth_scope_checker,ScopeChecker)``
|    The scope checker ``ScopeChecker`` selected by ``Options`` does not implement ``http_oauth_scope_checker_protocol``:
|        ``domain_error(http_oauth_scope_checker,ScopeChecker)``
|    The decorated response properties ``Properties`` are invalid:
|        ``domain_error(http_properties,Properties)``
|    The decorated response header ``Header`` violates normalized HTTP response semantics:
|        ``domain_error(http_header_semantics,Header)``
|    The decorated response property ``Property`` violates 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)