# Managing Rate Tables and Access Requests

The previous exercises—creating a line item for Elastic Access and provisioning it to the Elastic Access instance—laid the foundations for the steps in this section.

The following exercises demonstrate the steps that the producer, their customers, or the client application would perform using the REST APIs:

1. [Creating a Rate Table](#creating-a-rate-table)
2. [Identifying the Instance](#identifying-the-instance)
3. [Identifying Line Items Mapped to an Instance](#identifying-line-items-mapped-to-an-instance)
4. [Running an Access Request](#running-an-access-request)
5. [Checking Used Count](#checking-used-count)


For information about authorization requirements for the Dynamic Monetization APIs, see the Dynamic Monetization Authorization Guide. You can download this document from the [Product and License Center](https://flexerasoftware.flexnetoperations.com/) (login required).

For details about concepts in this section, see:

* [Access Requests](/guides/elastic-access-concepts-for-all-back-office-types#access-requests)
* [Items](/guides/elastic-access-concepts-for-all-back-office-types#items)
* [Rate Tables](/guides/elastic-access-concepts-for-all-back-office-types#rate-tables)
* [Sessions](/guides/elastic-access-concepts-for-all-back-office-types#sessions)


## Creating a Rate Table

**Authorization**: administration token

**Endpoint information**: [Create a rate table](/apis/openapispec/rate-tables/postratetables)

In this step, you use the **/rate-tables** endpoint to create a simple rate table. The rate table series is PublicationApps and it specifies the rates for the following products:

| Product | Version | Rate |
|  --- | --- | --- |
| **PhotoPrint** | 1.0 | 3 |
| **SignPrint** | 1.0 | 4 |
| **CADPrint** | 2.0 | 7 |


Send a POST request to the **/provisioning/api/v1.0/rate-tables** endpoint to create a rate table. Use the values as described in the following table:

| Item | Description |
|  --- | --- |
| **URI** | **/provisioning/api/v1.0/rate-tables** |
| **Method** | POST |
| **Query parameters** | N/A |
| **Request body** | 
```
{
  "effectiveFrom": 1698849852000,
  "series": "PublicationApps",
  "version": "1",
  "items": [
    {
      "name": "PhotoPrint",
      "version": "1.0",
      "rate": 3
    },
    {
      "name": "SignPrint",
      "version": "1.0",
      "rate": 4
    },
    {
      "name": "CADPrint",
      "version": "2.0",
      "rate": 7
    }
  ]
}
```
 |


**Sample Response**

If the rate table has been created (status 201), a message indicates the successful outcome:


```
{
    "message": "Rate table successfully saved"
}
```

To see the rate table that you created, send a GET call to **/provisioning/api/v1.0/rate-tables**.

## Identifying the Instance

**Authorization**: administration token

**Endpoint information**: [Get a list of instances](/apis/openapispec/instances/listinstances)

The instance whose short name contains "def-inst"—for example, ACME-def-inst, where ACME is the customer name—is always the instance used for auto-provisioning line items to Elastic Access.

Producers should send a GET call to **/provisioning/api/v1.0/instances** to identify the Elastic Access instances which host the line items belonging to customers.

| Item | Description |
|  --- | --- |
| **URI** | **/provisioning/api/v1.0/instances** |
| **Method** | GET |
| **Query parameters** | `next`, `size` |
| **Request body** | N/A |


**Sample Response**

If the request was successful, the response returns the instance information:


```JSON
{
  "content": [
    {
      "id": "d889a651-123a-456b-78d9-60d6de8cfes9",
      "shortName": "ACME-def-inst",
      "accountId": "ACME",
      "defaultInstance": true,
      "created": 1695821887865,
      "modified": 1695821887865
    }
  ],
  "next": "0"
}
```

## Identifying Line Items Mapped to an Instance

**Authorization**: administration token or client token

**Endpoint information**: [Get a list of line items](/apis/openapispec/line-items/getactivationsforinstance)

Send a GET request to **/provisioning/api/v1.0/instances/{instanceId}/line-items** to receive a list of line items that are associated with a specific Elastic Access instance. Pass the `{instanceId}` as a path parameter to identify the specific instance for which you want to see line items.

| Item | Description |
|  --- | --- |
| **URI** | **/provisioning/api/v1.0/instances/{instanceId}/line-items** |
| **Method** | GET |
| **Path parameters** | `instanceId`: Use the ID returned by the **/provisioning/api/v1.0/instances** API.
In the step, [Identifying the Instance](#identifying-the-instance), the instance ID `d889a651-123a-456b-78d9-60d6de8cfes9` was returned. |
| **Request body** | N/A |


Calling **/provisioning/api/v1.0/instances/{instanceId}/line-items** using GET also retrieves the line item status: DEPLOYED, INACTIVE, or OBSOLETE.

**Sample Response**

If the request was successful, the response returns the line item information. Note that the activation ID and quantity match the values that you provided in the task in [Configuring the Elastic Access Line Item](/tutorials/preparing-your-dynamic-monetization-instance-fno#configuring-the-elastic-access-line-item).


```JSON
[
  {
    "activationId": "ACT01-Elastic",
    "instanceId": "64d2028c-ae87-4069-a624-66089d957ef9"
    "start": 1695772800000,
    "end": 1790380800000,
    "quantity": 1000,
    "used": 0,
    "attributes": {
      "elastic": true,
      "rateTableSeries": "PublicationApps"
    }
  }
]
```

## 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** AP.
In the step, [Identifying the Instance](#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](#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.

## Checking Used Count

**Authorization**: administration token or client token

**Endpoint information**: [Get a list of line items](/apis/openapispec/line-items)

If you call the **/provisioning/api/v1.0/instances/{instanceId}/line-items** endpoint again, you will notice in the response that the "used" count has been incremented (because 44 tokens have been charged in the previous step, [Running an Access Request](#running-an-access-request):


```
[
  {
    "activationId": "ACT01-Elastic",
    "instanceId": "64d2028c-ae87-4069-a624-66089d957ef9"
    "start": 1695772800000,
    "end": 1790380800000,
    "quantity": 1000,
    "used": 44,
    "attributes": {
      "elastic": true,
      "rateTableSeries": "PublicationApps"
    }
  }
]
```

We do not recommend use this method of checking used counts other than in development, or troubleshooting particular situations. Do not send the request frequently or in rapid succession. It will have an impact on the system's ability to respond to access requests, which are its highest priority. Instead, you should use the Data Warehouse for tracking usage.