diff --git a/docs/user/api/cross-site-requests.rst b/docs/user/api/cross-site-requests.rst new file mode 100644 index 00000000000..2e1d38a1ed0 --- /dev/null +++ b/docs/user/api/cross-site-requests.rst @@ -0,0 +1,36 @@ +Cross-site requests +=================== + +Cross site requests are allowed for the following endpoints: + +- :ref:`/api/v2/footer_html/ ` +- :ref:`/api/v2/search/ ` +- :ref:`/api/v2/embed/ ` +- :ref:`/api/v2/sustainability/ ` +- :ref:`/api/v3/embed/ ` + +Except for the sustainability API, all of the above endpoints +don't allow you to pass credentials in cross-site requests. +In other words, these API endpoints allow you to access **public information only**. + +On a technical level, this is achieved by implementing the CORS_ standard, +which is supported by all major browsers. +We implement it such way that it strictly match the intention of the API endpoint. + +.. _CORS: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing + +Cookies +------- + +On |org_brand|, our session cookies have the ``SameSite`` attribute set to ``None``, +this means they can be sent in cross site requests. +This is needed for our sustainability API only, +to not show ads if the current user is a :ref:`Gold User `. +All resources in |org_brand| are public, you don't need to pass cookies to make use +of our allowed APIs from other sites. + +On |com_brand|, our session cookies have the ``SameSite`` attribute set to ``Lax``. +This means that browsers will not include them in cross site requests. +If you need to have access to versions that the current user has permissions over, +you can make use of our proxied APIs, they can be accessed from docs domains with the `/_/` prefix. +For example, you can make use of our search API from `/_/api/v2/search/`. diff --git a/docs/user/api/index.rst b/docs/user/api/index.rst index 99a0878de4b..bb2ea66d1d6 100644 --- a/docs/user/api/index.rst +++ b/docs/user/api/index.rst @@ -12,3 +12,4 @@ from Read the Docs. v3 v2 + cross-site-requests diff --git a/docs/user/api/v2.rst b/docs/user/api/v2.rst index 05f71d8af45..367b4224d96 100644 --- a/docs/user/api/v2.rst +++ b/docs/user/api/v2.rst @@ -408,7 +408,6 @@ There are some undocumented endpoints in the API. These should not be used and could change at any time. These include: -* The search API (``/api/v2/search/``) * Endpoints for returning footer and version data to be injected into docs. (``/api/v2/footer_html``) * Endpoints used for advertising (``/api/v2/sustainability/``)