Managing sessions usually involves the following tasks:
- Creating a Session
- Making a Session-Based Access Request
- Sending a Heartbeat
- Halting a Session
- Ending a Session
The client application initiates a session by issuing a POST to the /api/v1.0/sessions endpoint. The request body must contain the following:
- The instance that the session should run in.
- For authorization, a JWT which must contain an instance ID which matches the instance ID included in the headers.
The API returns a UUID identifying the session, which is generated by Elastic Access, and which subsequent session activity must use. (It is not possible for the producer’s software to specify a session ID. It can only be generated by Elastic Access.)
When a session is first created, it is in an IDLE state.
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.
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.
- Rollback, using the field
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.
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 three cases listed above, 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.
Once a client application has made a successful access request in a session, it must send a regular heartbeat to the session to confirm that the client is still using the items. The application must do this using a GET to the /api/v1.0/sessions/{sessionID}/heartbeat endpoint. Elastic Access must receive a heartbeat within 30 minutes of the last automatic charge made by the session.
The client must read the response to the heartbeat. If the response is a status 204, the client can continue using the application. If any other status is returned, the client should not continue using the application and ought to close it.
Note that the client application is not required to send a heartbeat after the initial charge. However, it must send a heartbeat after each automatically repeated charge to keep the session going. The application should not send heartbeats more frequently than required.
If Elastic Access does not receive a heartbeat within 30 minutes of the last automatic charge, it assumes that the client is no longer using the most recently requested items and that the most recent automatic charge was made in error. Hence Elastic Access does the following:
- Refunds tokens charged in the last automatic charge.
- Sets the session to a TERMINATED state.
- No longer accepts access requests for the session.
If the client wants to start using an application or items again, it must restart the process by creating a new session and requesting items.
For more information about automatic charges, see Automatic Charging Concepts.
The following sequence lists the events that occur when a client application requests an item as part of a session:
- 0 minutes: Start of timeline. The client application requests items. Elastic Access makes charge 1 and sends usage information to the data warehouse.
- 60 minutes: Automatic charge 2 is made after one hour. Usage information is sent to the data warehouse.
- Within 30 minutes of automatic charge 2: The client application sends a heartbeat.
- 120 minutes: Automatic charge 3 is made. Usage information is sent to the data warehouse.
- 150 minutes: 30 minutes have passed since the last automatic charge (charge 3), without Elastic Access receiving a heartbeat from the application. Elastic Access assumes that the client has shut down the application and is no longer using it. Elastic Access therefore does the following:
- Ends the session. The session accepts no more access requests and its state changes to TERMINATED.
- Issues a refund for the entire automatic charge 3 made at 120 minutes and sends this information to the data warehouse.
Elastic Access also allows temporarily halting a session. This can be useful in scenarios where a client application wants to stop using an item temporarily and then pick it up and continue using it within the same session at a later point in time.
To halt a session, the client application sends an empty list of items in a session-based access request. Elastic Access refunds any charges for the remainder of the current session and changes the session state to IDLE. No automatic charges are made while the session is IDLE. When the client application is ready to continue its use of the same item, or different items, it needs to send a new access request. This returns the session state to ACTIVE. The session continues and the client application can request and use items until it ends.
Halting a session is useful for tracking the end-to-end use of an application, because it avoids the fragmentation of usage data. In addition, it helps customers maintain costing allocation to a single business activity or accounting event.
Sessions can be halted—that is, remain in an IDLE state—for a maximum of 30 days. After that, the session is terminated and can no longer be used. Once the session has been terminated, an error is returned to a client application if it tries to use that session.
Key points
- Sending an empty list of items halts a session.
- Halted sessions are in an IDLE state.
- Halting a session triggers a refund (if applicable) of the remainder of the current charging hour.
- No automated charges are made while the session is IDLE.
- No heartbeat is required while the session is IDLE.
- Sending a non-empty access request returns the session to ACTIVE.
- Sessions can be halted for 30 days maximum.
To ensure that token consumption is calculated for the precise time the items have been in use, the client application should be configured to close a session it is using when it stops running.
The client application ends the session using a DELETE call to the /api/v1.0/sessions/{sessionID} endpoint. After a session has been deleted, it cannot be used again. Subsequent activity requires the creation of a new session, resulting in a new session ID.
Elastic Access automatically ends a session in the following scenarios:
- The software fails to send a heartbeat in the required time (see Sending a Heartbeat).
- Insufficient tokens are available to make the automatic charge. A deleted or ended session is placed in a TERMINATED state.