Skip to main content

Start extraction session

POST 
/session/start

Used to initiate a new session with DataWollet, which can be used to extract data from multiple documents over a period of time prior to its expiry. DataWollet does not generally persist data beyond the expiry of a session, and sessions can be explicitly terminated using the appropriate endpoint.

Sessions can be partitioned using a client-supplied key, which ensures that session IDs are unique to that partitioning key. This can be used to isolate sessions per end-user or per device, for example. When integrated with a system that has its own sessions, using a partitioning key tied to that system's session ID is recommended to prevent session fixation attacks.

If an existing session ID is supplied, the session will be resumed if it is still valid. If the session ID is invalid or expired, a new session will be started.

When a session is continued, the previous requests made within that session are returned in the response, allowing the client to reconstruct the session state.

Session keys are used to protect session data, and are sent to the client as partitioned cookies. These cookies should be stored securely by the client and sent with each request that references the session. If the session key is not supplied or is invalid, the session will be treated as invalid and a new session will be started.

When using confidential clients, the session key cookie can be used but is not strictly required as sessions are scoped to the client ID. For public clients such as web SPAs, the session key cookie is an important security mechanism. Cross-origin use of the session key cookie is made possible using partitioned cookies (CHIPS), which allows the cookie to be sent in cross-origin requests while still enforcing same-site restrictions to prevent CSRF attacks. For public clients, a valid Origin header is important to identify the correct client configuration.

If authorised with the envelopes:create scope, clients can also create an envelope as part of the session creation process, which allows the documents and data to be accessed again at a later date by providing the same envelope ID and key. If clients have an existing envelope and the envelopes:read scope, they can attach that envelope to the session and therefore read (and write if they have the envelopes:write scope) the documents and data across multiple sessions. The retention period for an envelope is client-specific and is independent of the session expiry - envelopes will remain available until their retention period expires, even if all sessions that accessed them have expired.

All sessions have a maximum duration that cannot be exceeded, even if the client requests a longer session timeout. Use envelopes if durable storage is required beyond the maximum session duration.

Request​

Responses​

Session started successfully