> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forestreet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate your API requests

Most interactions with our API require authentication to ensure that only authorized users can access or modify data.
There are multiple ways to be authenticated.

<Card title="API Header Key" icon="key">
  The simplest way to authenticate your API requests is by using an API token. This token should be included in the
  `x-api-key` header of your requests:

  <CodeGroup>
    ```sh Shell theme={null}
    curl -H 'x-api-key: <api_token>' <host>/v2/users/me
    ```

    ```javascript Javascript Fetch theme={null}
    import { fetch } from "node-fetch";

    const authHeaders = {
      "x-api-key": "<api_token>",
    };
    await fetch("<host>/v2/users/me", {
      method: "GET",
      headers: authHeaders,
    });
    ```

    ```javascript Javascript Axios theme={null}
    import axios from "axios";

    const authHeaders = {
      "x-api-key": "<api_token>",
    };
    await axios.get("<host>/v2/users/me", {
      headers: authHeaders,
    });
    ```

    ```python Python Blocking theme={null}
    import requests
    auth_headers = {
        'x-api-key': '<api_token>'
    }
    response = requests.get('<host>/v2/users/me', headers=auth_headers)
    ```

    ```python Python Async theme={null}
    import httpx
    auth_headers = {
        'x-api-key': '<api_token>'
    }
    async with httpx.AsyncClient() as client:
        response = await client.get('<host>/v2/users/me', headers=auth_headers)
    ```
  </CodeGroup>

  This authentication is stateless, meaning that the authentication is only valid for the current request. All subsequent
  requests must include the API token in the header. This prevents the need for timed session management.

  These keys should be kept confidential. If compromised, it's crucial to revoke and generate a new token immediately. To
  do this, reach out to us at [info@forestreet.com](mailto:info@forestreet.com).

  Each token is associated with specific permissions, granting access to various levels and types of data. Speak to us
  about the various levels of data access that you require.

  <Tip>
    This method is suitable for:

    * backend services
    * server-side applications
    * scripts
  </Tip>

  <Warning>
    This method is **not suitable** for: - client-side applications (e.g., web browsers, mobile apps) as it exposes the
    API key
  </Warning>
</Card>

<Card title="Email, Password and Cookie Session" icon="user">
  If you have an user interface which allows users to log in, you can authenticate users using their input credentials.

  This is done through the [`POST /v2/auth/sign-in`](/api-reference/endpoints/auth/sign-in) endpoint:

  <CodeGroup>
    ```sh Shell theme={null}
    curl -X POST -H 'Content-Type: application/json' -d '{"email": "<email>", "password": "<password>"}' <host>/v2/auth/sign-in
    ```

    ```javascript Javascript Fetch theme={null}
    import { fetch } from "node-fetch";

    const response = await fetch("<host>/v2/auth/sign-in", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        email: "<email>",
        password: "<password>",
      }),
    });
    ```

    ```javascript Javascript Axios theme={null}
    import axios from "axios";

    const response = await axios.post("<host>/v2/auth/sign-in", {
      email: "<email>",
      password: "<password>",
    });
    ```

    ```python Python Blocking theme={null}
    import requests
    with requests.Session() as session:
        response = session.post('<host>/v2/auth/sign-in', json={
            'email': '<email>',
            'password': '<password>'
        })
        # Any subsequent requests using this session will include the cookie automatically
    ```

    ```python Python Async theme={null}
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.post('<host>/v2/auth/sign-in', json={
            'email': '<email>',
            'password': '<password>'
        })
        # Any subsequent requests using this client will include the cookie automatically
    ```
  </CodeGroup>

  The response will include a `Set-Cookie` header with a session cookie. This cookie should be stored in the user's
  browser or application, and included in subsequent requests to the API. The cookie will be used to authenticate the user
  for the duration of the session.

  <Tip>
    This method is suitable for: - web applications - mobile applications - any application where users log in with email
    and password
  </Tip>

  <Warning>
    This method is **not suitable** for: - backend services or scripts, as it requires storing user credentials which can
    lead to security issues
  </Warning>
</Card>

<Card title="Session ID" icon="clock">
  For [iFrame integrations](/api-reference/guides/iframe-integration), you will need to be able to authenticate your user in a browser
  for a limited time period, without

  * exposing your API key to the frontend, or
  * the user having their login credentials at all.

  This is done through the [`GET /v2/auth/session`](/api-reference/endpoints/auth/get-session-id) endpoint:

  <CodeGroup>
    ```sh Shell theme={null}
    curl -H 'x-api-key: <api_token>' <host>/v2/auth/session
    ```

    ```javascript Javascript Fetch theme={null}
    import { fetch } from "node-fetch";

    const authHeaders = {
      "x-api-key": "<api_token>",
    };
    const response = await fetch("<host>/v2/auth/session", {
      method: "GET",
      headers: authHeaders,
    });
    ```

    ```javascript Javascript Axios theme={null}
    import axios from "axios";

    const authHeaders = {
      "x-api-key": "<api_token>",
    };
    const response = await axios.get("<host>/v2/auth/session", {
      headers: authHeaders,
    });
    ```

    ```python Python Blocking theme={null}
    import requests
    auth_headers = {
        'x-api-key': '<api_token>'
    }
    response = requests.get('<host>/v2/auth/session', headers=auth_headers)
    ```

    ```python Python Async theme={null}
    import httpx
    auth_headers = {
        'x-api-key': '<api_token>'
    }
    async with httpx.AsyncClient() as client:
        response = await client.get('<host>/v2/auth/session', headers=auth_headers)
    ```
  </CodeGroup>

  This will return a JWT token, which will include a `accessToken` field:

  <CodeGroup>
    ```json Session Response theme={null}
    {
      "idToken": "...",
      "accessToken": "<session_id>",
      "refreshToken": "...",
      "expiresIn": 3600,
      "checksum": "..."
    }
    ```
  </CodeGroup>

  For our purposes, only `accessToken` is required. This token should be included in the iFrame URL as a query parameter:

  <CodeGroup>
    ```html iframe-integration.html theme={null}
    <iframe
      src="https://ailsa.forestreet.com/path/to/page?sessionId=<session_id>"
      width="100%"
      height="600px"
      frameborder="0"
    />
    ```
  </CodeGroup>

  Then all subsequent requests made within the iFrame will automatically include the session ID in the request headers,
  allowing Forestreet to authenticate the user without requiring them to log in again.

  <Tip>
    This method is suitable for: - iFrame integrations, or - applications where you need to give an unauthenticated user
    access to Forestreet features for a limited duration, and that secret has to be exposed to the frontend.
  </Tip>

  <Warning>
    This method is **not suitable** for: - backend services or scripts, as the session may not live long enough for all
    the subsequent requests to complete
  </Warning>
</Card>