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.

API Header 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:
curl -H 'x-api-key: <api_token>' <host>/v2/users/me
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.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.
This method is suitable for:
  • backend services
  • server-side applications
  • scripts
This method is not suitable for: - client-side applications (e.g., web browsers, mobile apps) as it exposes the API key

Email, Password and Cookie Session

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 endpoint:
curl -X POST -H 'Content-Type: application/json' -d '{"email": "<email>", "password": "<password>"}' <host>/v2/auth/sign-in
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.
This method is suitable for: - web applications - mobile applications - any application where users log in with email and password
This method is not suitable for: - backend services or scripts, as it requires storing user credentials which can lead to security issues

Session ID

For iFrame integrations, 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 endpoint:
curl -H 'x-api-key: <api_token>' <host>/v2/auth/session
This will return a JWT token, which will include a accessToken field:
{
  "idToken": "...",
  "accessToken": "<session_id>",
  "refreshToken": "...",
  "expiresIn": 3600,
  "checksum": "..."
}
For our purposes, only accessToken is required. This token should be included in the iFrame URL as a query parameter:
<iframe
  src="https://ailsa.forestreet.com/path/to/page?sessionId=<session_id>"
  width="100%"
  height="600px"
  frameborder="0"
/>
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.
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.
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