Skip to main content
Documentation Powered by Redocly

Metering API (1.1.2)

Download OpenAPI specification:Download

The metering API enables you to track usage of specific resources by creating and managing transactions. Transactions are assigned to keys, which can represent users, etc.

Authentication

ApplicationAuth

Security Scheme Type API Key
Header parameter name: Authorization

Keys

Initialize Key

Keys must be initialized before you can begin tracking their usage. You should specify accessible resources in items, along with any quantity limits or date cutoffs.

The key can only be reset or modified by the user that created it.

Authorizations:
ApplicationAuth
    Request Body schema: application/json
    audiences
    required
    Array of strings (Id) [ 1 .. 10 ] characters [ items [ 1 .. 64 ] characters [a-zA-Z0-9_-]+ ]
    keyId
    string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+
    required
    Array of objects (Resource) [ 1 .. 10 ] characters [ items ]

    Responses

    Request samples

    Content type
    application/json
    {
    • "audiences": [
      ],
    • "keyId": "string",
    • "resources": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "keyId": "string"
    }

    Describe Key

    Get resource usage data for a specific key.

    Authorizations:
    ApplicationAuth
      path Parameters
      keyId
      required
      string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+

      Responses

      Response samples

      Content type
      application/json
      {
      • "keyId": "string",
      • "resources": [
        ]
      }

      Update Key

      Update a key's audience and resource lists. At least one of audiences or resources must be provided.

      Authorizations:
      ApplicationAuth
        path Parameters
        keyId
        required
        string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+
        Request Body schema: application/json
        audiences
        Array of strings

        If provided, overwrites the list of audiences allowed to create transactions on this key.

        Array of objects (Resource) [ items ]

        Updates limit and accessUntilDate on specified resources. If either is left undefined it will remove the respective value as long as the resourceId is passed. Every resourceId provided must already exist, but if a resourceId is not passed it will not be updated.

        Responses

        Request samples

        Content type
        application/json
        {
        • "audiences": [
          ],
        • "resources": [
          ]
        }

        Response samples

        Content type
        application/json
        {
        • "audiences": [
          ],
        • "keyId": "string",
        • "resources": [
          ]
        }

        Reset Key

        Reset the usage for all resources atomically. Returns the key's usage prior to being reset - equivalent to Describe Key before a reset. The resetPending attribute gives the user the option to either fail if there's a pending txn, carry it over to the new key, or reset it to zero. Defaults to 'FAIL'. Resources that have the reset behavior set to TRANSFER will have their usage roll over.

        Authorizations:
        ApplicationAuth
          path Parameters
          keyId
          required
          string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+
          Request Body schema: application/json
          resetPending
          string (ResetPendingEnum)
          Default: "FAIL"
          Enum: "FAIL" "WIPE" "TRANSFER"
          Array of objects (Resource) [ items ]

          Responses

          Request samples

          Content type
          application/json
          {
          • "resetPending": "FAIL",
          • "resources": [
            ]
          }

          Response samples

          Content type
          application/json
          {
          • "keyId": "string",
          • "resources": [
            ]
          }

          Transactions

          List Transactions

          Get list of transactions for a specific key.

          Authorizations:
          ApplicationAuth
            path Parameters
            keyId
            required
            string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+
            query Parameters
            nextToken
            string (NextToken) <= 4096 characters ^[a-zA-Z0-9_-]+$
            status
            required
            string[PENDING|CONFIRMED|CANCELED|EXPIRED]([,PENDIN...
            Example: status=CANCELED,EXPIRED

            Results only contain transactions with the specified status type(s).

            Responses

            Response samples

            Content type
            application/json
            {
            • "items": [
              ],
            • "nextToken": "string"
            }

            Create Transaction

            Create a new transaction. Quantity should be an upper bound if unknown, as adjustments (via PUT /transactions/transactionId) can only decrease the quantity. Returns the transactionId which should be kept track of by your application in order to describe, confirm, update, or cancel the transaction.

            Authorizations:
            ApplicationAuth
              Request Body schema: application/json
              commit
              boolean
              Default: false

              Immediately commit the transaction

              expiration
              number [ 0 .. 86400 ]
              Default: 3600

              Expiration of the transaction in seconds.

              keyId
              required
              string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+
              quantity
              required
              number

              An upper bound on the quantity consumed by the key. This can be reduced via PUT /transactions/{transactionId}

              resourceId
              required
              string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+

              Responses

              Request samples

              Content type
              application/json
              {
              • "commit": false,
              • "expiration": 120,
              • "keyId": "string",
              • "quantity": 0,
              • "resourceId": "string"
              }

              Response samples

              Content type
              application/json
              {
              • "transactionId": "string"
              }

              Cancel Transaction

              Cancel a transaction.

              Authorizations:
              ApplicationAuth
                path Parameters
                transactionId
                required
                string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+

                Responses

                Describe Transaction

                Get specific transaction details.

                Authorizations:
                ApplicationAuth
                  path Parameters
                  transactionId
                  required
                  string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+

                  Responses

                  Response samples

                  Content type
                  application/json
                  {
                  • "expirationDate": "2019-08-24T14:15:22Z",
                  • "keyId": "string",
                  • "quantity": 0,
                  • "resourceId": "string",
                  • "status": "PENDING",
                  • "transactionId": "string"
                  }

                  Commit Transaction

                  Commit a transaction.

                  Authorizations:
                  ApplicationAuth
                    path Parameters
                    transactionId
                    required
                    string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+

                    Responses

                    Update Transaction

                    Update transaction quantity to a reduced value. An increase isn't allowed as it could conflict with limits (initial transaction quantities should be an upper bound). Instead, a new transaction should be initiated.

                    Transactions can only be updated by the user and application that created the transaction.

                    Authorizations:
                    ApplicationAuth
                      path Parameters
                      transactionId
                      required
                      string (Id) [ 1 .. 64 ] characters [a-zA-Z0-9_-]+
                      Request Body schema: application/json
                      quantity
                      required
                      number

                      The (reduced) quantity consumed.

                      Responses

                      Request samples

                      Content type
                      application/json
                      {
                      • "quantity": 0
                      }