# Running an Access Request This section is broken down into two exercises, to demonstrate the different ways of making an access request: - [Running a One-Off Access Request](/tutorials/running-an-access-request#running-a-one-off-access-request) - [Running a Session-Based Access Request](/tutorials/running-an-access-request#running-a-session-based-access-request) ### Note Regarding Sample Users The exercises in this section assume the request should be registered against a fictitious user called Lisa Barry, which will be shown in the usage entry for the request. You might prefer to register the request against the name or ID of a device, and you should change the type and value in the requester fields appropriately. ## Running a One-Off Access Request **Authorization**: administration token or client token **Endpoint information**: [Access request for elastic tokens ](/apis/openapispec/non-session-access-request/postaccessrequest) This step demonstrates how an application run by the customer Lisa Barry requests the following items using the elastic/api/v1.0/instances/{instanceId}/access-request endpoint: - 10 counts of PhotoPrint, version 1.0 - 2 counts of CADPrint, version 2.0 You need to pass the `{instanceId}` as a path parameter to identify the specific instance from which you request line items. This form of access request is intended for single use of the requested items. It does not initiate a session or result in repeated charges for the items over time. It is also not possible to "return" the items or obtain a full or partial refund for the tokens charged. For more information about sessions, see [Sessions](/guides/sessions/session-concepts). | Item | Description | | --- | --- | | URI | **elastic/api/v1.0/instances/{instanceId}/access-request** | | Method | POST | | Path parameters | `instanceId`: Use the ID returned by the **/provisioning/api/v1.0/instances** API In the exercise, [Identifying the Instance](/tutorials/identifying-the-instance), the instance ID `d889a651-123a-456b-78d9-60d6de8cfes9` was returned. | | Request body | ``` { "requester": { "type": "user", "value": "LisaBarry" }, "requestedItems": [ { "item": "PhotoPrint", "requestedVersion": "1.0", "count": 10, }, { "item": "CADPrint", "requestedVersion": "2.0", "count": 2, } ] } ``` | ### Sample Response The sample response displays information about the requested items, PhotoPrint and CADPrint. The line item with activation ID ACT01-Elastic was charged 44 tokens in total: - 10 counts at a rate of 3 = 30 tokens for PhotoPrint - 2 counts at a rate of 7 = 14 tokens for CADPrint. ``` { "correlationId": "5c8ec4fd-f17f-4657-bf09-74a97ddc9f8b", "requester": { "type": "user", "value": "LisaBarry" }, "requestedItems": [ { "item": "PhotoPrint", "requestedVersion": "1.0", "count": 10, "status": { "code": "101", "description": "Successfully checked out" }, "totalTokensCharged": 30, "lineItems": [ { "rate": 3, "activationId": "ACT01-Elastic", "tokensCharged": 30 } ] }, { "item": "CADPrint", "requestedVersion": "2.0", "count": 2, "status": { "code": "101", "description": "Successfully checked out" }, "totalTokensCharged": 14, "lineItems": [ { "rate": 7, "activationId": "ACT01-Elastic", "tokensCharged": 14 } ] } ] } ``` ## Running a Session-Based Access Request This section demonstrates how an application initiates a session and requests items. It is broken down into the following steps: 1. [Initiating a Session](/tutorials/running-an-access-request#initiating-a-session) 2. [Requesting Items During the Session](/tutorials/running-an-access-request#requesting-items-during-the-session) 3. [Closing the Session](/tutorials/running-an-access-request#closing-the-session) ### Initiating a Session **Authorization**: administration token or client token **Endpoint information**: [Request a new session](/apis/openapispec/sessions/createsession) Issue a POST to the **/api/v1.0/sessions** endpoint to create a new session. The request body must contain the following: - The instance that the session should run in. (See also [Identifying the Instance](/tutorials/managing-rate-tables-and-access-requests#identifying-the-instance).) - For authorization, a JWT which must contain an instance ID which matches the instance ID included in the headers. When the session is first created, it is in an IDLE state. | Item | Description | | --- | --- | | URI | **/api/v1.0/sessions** | | Method | POST | | Path parameters | N/A | | Request body | ```JSON { "instanceId": "64d2028c-ae87-4069-a624-66089d957ef9" } ``` | #### Sample Response The response contains a UUID identifying the session, which is generated by Elastic Access. Take note of the ID that is returned in your example, because it is used in subsequent exercises. ``` { "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"" } ``` ### Requesting Items During the Session **Authorization**: administration token or client token **Endpoint information**: [Elastic access request in the context of a session ](/apis/openapispec/sessions/putsessionaccessrequest) In this example, make a PUT call to the /api/v1.0/sessions/{sessionId} endpoint to request the following items: - 10 counts of PhotoPrint, version 1.0 - 2 counts of CADPrint, version 2.0 The request must include the `{sessionId}` as a path parameter to identify the session during which it requests items. | Item | Description | | --- | --- | | URI | **/api/v1.0/sessions/{sessionID}** | | Method | PUT | | Path parameters | `sessionId`: Use the ID returned by the **/api/v1.0/sessions** API in the previous step, [Initiating a Session](/tutorials/running-an-access-request#initiating-a-session). | | Request body | ```JSON { "requester": { "type": "user", "value": "LisaBarry" }, "rollbackOnDeny": true, "requestedItems": [ { "item": "PhotoPrint", "version": "1.0", "count": 10, } { "item": "CADPrint", "version": "2.0", "count": 2 } ] ``` | #### Sample Response The sample response displays information about the items, PhotoPrint and CADPrint, that were requested during the session. As in the previous procedure, the line item with activation ID ACT01-Elastic was charged 44 tokens in total: - 10 counts at a rate of 3 = 30 tokens for PhotoPrint - 2 counts at a rate of 7 = 14 tokens for CADPrint. ```JSON { "requestedItems": [ { "count": 10, "item": "PhotoPrint", "version": "1.0", "totalTokensCharged": 30, "lineItems": [ { "rate": 3, "activationId": "ACT01-Elastic", "tokensCharged": 30 } ], "status": { "code": "101", "description": "Successfully checked out" }, }, { "count": 2, "item": "CADPrint", "version": "2.0", "totalTokensCharged": 14, "lineItems": [ { "rate": 7, "activationId": "ACT01-Elastic", "tokensCharged": 14 } ], "status": { "code": "101", "description": "Successfully checked out" }, } ], "requester": { "type": "user", "value": "LisaBarry" }, "correlationId": "5c8ec4fd-f17f-4657-bf09-74a97ddc9f8b" } ``` ### Closing the Session **Authorization**: administration token or client token **Endpoint information**: [Close a Session](/apis/openapispec/sessions/closesession) Upon closing the PhotoPrint and CADPrint applications, issue a DELETE call to the **/api/v1.0/sessions/{sessionId}** endpoint to close the session. Closing a session ensures that token consumption is calculated for the precise time the items have been in use. 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. The request must include the `{sessionId}` as a path parameter to identify the session to be closed. | Item | Description | | --- | --- | | URI | **/api/v1.0/sessions/{sessionID}** | | Method | DELETE | | Path parameters | `sessionId`: Use the ID returned by the **/api/v1.0/sessions** API in the previous step, [Initiating a Session](/tutorials/running-an-access-request#initiating-a-session). | | Request body | N/A | #### Sample Response If the request was successful, the response returns code 200, indicating that the session was successfully closed.