Managing Rate Tables and Access Requests

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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
2. Identifying the Instance
3. Identifying Line Items Mapped to an Instance
4. Running an Access Request
5. Checking Used Count

Creating a Rate Table

Authorization: administration token

Endpoint information: Create a rate table

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:

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:

{
  "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"
}

Identifying the Instance

Authorization: administration token

Endpoint information: Get a list of instances

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.

Sample Response

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

{
  "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

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.

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.

[
  {
    "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
• 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

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.

{
  "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
2. Requesting Items During the Session
3. Closing the Session

Initiating a Session

Authorization: administration token or client token

Endpoint information: Request a new session

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.)
• 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.

{
"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

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.

{
"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.

{
  "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

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.

The request must include the {sessionId} as a path parameter to identify the session to be closed.

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

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:

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