API Access and Token Use
========================

.. contents::
   :local:

CITYNEXUS PRO API requests are authenticated with the same user session used in the CITYNEXUS PRO web interface. After logging in through the DestinE platform, the browser sends an access token to the CITYNEXUS PRO API in the HTTP ``Authorization`` header.

Get an access token
-------------------

1. Log in to CITYNEXUS PRO through the DestinE platform.
2. Open the browser developer tools and select the ``Network`` tab.
3. Refresh CITYNEXUS PRO or open a scenario, simulation, or map view so that the application makes an API request.
4. Select a request whose path starts with ``/api/v1/citynexus/``.
5. In the request headers, find ``Authorization: Bearer <token>`` and copy only the ``<token>`` value.

Treat the token like a password. Do not share it, commit it to source control, or paste it into public logs. Tokens expire; if an API request returns ``401 Unauthorized`` or ``403 Forbidden``, sign in again and copy a fresh token.

Use the token in an API request
-------------------------------

Use the token as a Bearer token in the ``Authorization`` header. Replace ``https://<citynexus-pro-host>`` with the CITYNEXUS PRO host you are using.

.. code-block:: bash

   export CITYNEXUS_TOKEN="<token>"
   export CITYNEXUS_API_URL="https://<citynexus-pro-host>"

   curl \
     -H "Authorization: Bearer ${CITYNEXUS_TOKEN}" \
     -H "Accept: application/json" \
     "${CITYNEXUS_API_URL}/api/v1/citynexus/scenarios?city=copenhagen"

For requests with a JSON body, also send the ``Content-Type`` header:

.. code-block:: bash

   curl \
     -X POST \
     -H "Authorization: Bearer ${CITYNEXUS_TOKEN}" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"scenarioId":"<scenario-id>","mobility_model_input":{}}' \
     "${CITYNEXUS_API_URL}/api/v1/citynexus/predictions?name=<prediction-name>"

Use the token in the API reference
----------------------------------

The API reference is available in the ``api/index.html`` page. To make authenticated requests from that page:

1. Open the API reference page in a browser.
2. Click ``Authorize``.
3. Paste the token value only, without the ``Bearer`` prefix.
4. Confirm the dialog, then use ``Try it out`` on an endpoint.

Swagger UI adds the ``Authorization: Bearer <token>`` header automatically after authorization.