> ## 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.
# Set Session Cookies
>
Using a JWT token and a checksum, this endpoint sets session cookies in the user's browser.
This is typically used in iFrames where a client's backend generates a JWT Token using its API key,
and the backend then asks the end user's browser to render an iFrame with the JWT Token embedded.
The iFrame then calls this endpoint to set the cookies in the browser.
The checksum is computed using HMAC with the tokens as input to ensure the tokens have not been tampered with.
If the checksum does not match, an error is thrown indicating that the tokens have been tampered with.
See also [the `GET /v2/auth/session` endpoint](/api-reference/endpoints/auth/get-session-id).
You can use this endpoint to set the cookies in the iFrame, then redirect the user to the desired page
using the [`redirectUrl`](#body-redirect-url) parameter.
## OpenAPI
````yaml put /v2/auth/session
openapi: 3.0.0
info:
title: Forestreet API
version: 1.0.0
description: API documentation for Forestreet API
servers:
- url: https://rest.forestreet.com
description: Forestreet API V2 server
security:
- apiKeyAuth: []
- bearerAuth: []
- sessionIdQuery: []
tags: []
paths:
/v2/auth/session:
put:
tags:
- Auth
summary: Set Session Cookies
description: |2-
Using a JWT token and a checksum, this endpoint sets session cookies in the user's browser.
This is typically used in iFrames where a client's backend generates a JWT Token using its API key,
and the backend then asks the end user's browser to render an iFrame with the JWT Token embedded.
The iFrame then calls this endpoint to set the cookies in the browser.
The checksum is computed using HMAC with the tokens as input to ensure the tokens have not been tampered with.
If the checksum does not match, an error is thrown indicating that the tokens have been tampered with.
See also [the `GET /v2/auth/session` endpoint](/api-reference/endpoints/auth/get-session-id).
You can use this endpoint to set the cookies in the iFrame, then redirect the user to the desired page
using the [`redirectUrl`](#body-redirect-url) parameter.
requestBody:
content:
application/json:
schema:
type: object
properties:
refreshToken:
type: string
pattern: ^[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)+$
description: Refresh token to set in cookies.
idToken:
type: string
pattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$
description: JWT ID token for the user.
checksum:
type: string
description: Mandatory checksum for the tokens.
redirectUrl:
type: string
format: uri
description: >-
If provided, redirects to this URL after setting cookies.
The URL must be within the Forestreet domain.
required:
- refreshToken
- idToken
- checksum
responses:
'204':
description: >-
Session validated, and cookies set successfully; no `redirectUrl`
provided.
headers:
Set-Cookie:
schema:
type: string
description: Authentication cookies set in the response headers.
required: true
description: Authentication cookies set in the response headers.
'302':
description: >-
Session validated, and cookies set successfully; redirecting user to
`redirectUrl`.
headers:
Set-Cookie:
schema:
type: string
description: Authentication cookies set in the response headers.
required: true
description: Authentication cookies set in the response headers.
Location:
schema:
type: string
format: uri
description: The URL to redirect to after setting cookies.
required: true
description: The URL to redirect to after setting cookies.
'400':
description: Bad Request - Invalid input
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
INVALID_INPUT:
value:
success: false
errorCode: INVALID_INPUT
message: Bad Request - Invalid input
'401':
description: Unauthorized - Invalid credentials, token or cookies
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- USER_NOT_CONFIRMED
- INVALID_CREDENTIALS
- INCOMPLETE_CREDENTIALS
- INVALID_SESSION_TOKEN
- FORCE_CHANGE_PASSWORD
- PASSWORD_RESET_REQUIRED
- PASSWORD_EXPIRED
- CODE_EXPIRED
- SESSION_EXPIRED
- UNAUTHORISED
- AUTHENTICATOR_ERROR
- SSO_ACCOUNT
- FORBIDDEN
- METHOD_NOT_ALLOWED
- INVALID_INPUT
- PATH_VALIDATION_FAILED
- QUERY_VALIDATION_FAILED
- BODY_VALIDATION_FAILED
- RESPONSE_VALIDATION_FAILED
- INVALID_OR_MALFORMED_JSON
- INTERNAL_SERVER_ERROR
- CONFIGURATION_ERROR
- SERVICE_UNAVAILABLE
- NOT_FOUND
- CONFLICT
- LIMIT_EXCEEDED
- REVIEW_ALREADY_PENDING
- REVIEW_NOT_PENDING
- REVIEW_PENDING
- REVIEW_INSUFFICIENT_DOMAINS
- QUOTA_EXCEEDED
- UNSUPPORTED_ENDPOINT_VERSION
- ENDPOINT_NOT_FOUND
- ENDPOINT_ALREADY_EXISTS
message:
type: string
detail:
type: object
additionalProperties:
nullable: true
required:
- success
- errorCode
examples:
UNAUTHORISED:
value:
success: false
errorCode: UNAUTHORISED
message: Unauthorized - Invalid credentials, token or cookies
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Pass a static API key for every request, provided by your customer
support.
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication, using a sessionId generated by `GET
/v2/auth/session`.
sessionIdQuery:
type: apiKey
in: query
name: sessionId
description: >-
Session ID passed as a query parameter for authentication, provided by
`GET /v2/auth/session`.
````