Making a Session-Based Access Request

The client application makes a session-based access request by sending a PUT to the /api/v1.0/sessions/{sessionID} endpoint. The request body must include a list of items for which tokens will be charged, and requester information identifying the user or device making the request.

General Behavior for Session-Based Access Requests

The following describes the behavior when an application makes an access request within a session:

•

For authorization, the request body must include a valid JSON Web Token (JWT). The JWT must contain an instance ID which matches the instance ID included in the headers.

•

When the request is made, the items requested will be charged for.

•

When one or more items are being charged for in a session, the session is in an ACTIVE state.

•

When an access request is made, the client application can specify the action to take if it is denied. Options are:

•

Rollback, using the field rollbackOnDeny = true. The items being charged for in a session will remain the same as they were before the access request and the automatic charge timing will not change. The session will remain ACTIVE.

•

Do not rollback, using the field rollbackOnDeny = false. The session moves to a TERMINATED state, halts the repeat charge process, refunds any tokens charged for the remainder of the automatic charge period, and it is not possible to make any more access requests to that session. A new session will be required to resume activity.

Behavior When Requesting Multiple Items Within a Session

The following describes the behavior when an application requests multiple items:

•

If multiple items are requested in a session, Elastic Access fulfills all the items, or none of the items. If it is only possible to fulfill some of the items then the entire request fails, and an error response is returned.

Note:This behavior differs from that of one-off access requests, where Elastic Access attempts to fulfill and charge for as many items as possible. See also Requesting Multiple Items in One-Off Access Request.

•

Once the first set of items has been requested, Elastic Access automatically repeats the charge for those same items once per hour, until one of the following occurs:

•

The session is deleted.

•

The software fails to send a heartbeat in the required time (see Sending a Heartbeat).

•

Insufficient tokens are available to make the automatic charge.

In all cases, the session status changes to TERMINATED and no further access requests are possible. A new session is needed for subsequent activity.

•

Multiple access requests can be made to a session, changing the combination of items that are being charged for in the session. When a subsequent access request is made, Elastic Access restarts the timer for automatic charges, always making repeat charges at hourly intervals after the most recent access request.

•

Access requests are regenerative. Therefore, any access request replaces the previous list of items that were requested.

•

An access request may contain an empty list of items, which is how software “returns” the items it is using to pause repeat charging. The session state returns to an IDLE state. See also Halting a Session.