Introducing Provisioning API And Detailed Usage Reporting

Today, we’re thrilled to introduce a brand-new provisioning API that enables Enterprise customers to conveniently manage API keys for their clients, apps, and websites. Alongside these new API additions, we’re also unveiling detailed usage statistics on a per-API-key basis, accessible from both API endpoints and the Optidash Account interface. This enhancement offers greater transparency and control, empowering users to monitor and optimize their usage more effectively.

Usage Reporting in the Optidash Account

Chances are, not all members of your organization are technical individuals capable of programmatically querying our endpoints to retrieve usage statistics per API key. To accommodate users who typically operate within the browser environment, we’ve redesigned the “API Keys” view in the Optidash Account.

Introducing the “Manage” menu within the API Keys list. The “Show usage” entry is pretty self-explanatory — it’s where usage statistics can be accessed. A pair of simple date-pickers has been added to allow for fine-tuning of the time range. Additionally, the bottom section now displays cumulative usage for the selected date range, including individual requests and input volume in GBs. This enhancement aims to provide users with a more intuitive and accessible way to monitor their API key usage.

Here’s a quick screencast demostrating how this brand new UI behaves works:

Provisioning API

We’re excited to announce the introduction of a new /1.0/keys endpoint, specifically designed for API Keys management. With this endpoint, users can add, modify, and retrieve API keys along with their respective usage statistics. It’s important to note that requests to this endpoint must be authenticated solely with the master (primary) API key for security reasons. This enhancement streamlines the process of managing API keys and accessing usage data, providing users with greater control and insight into their Optidash account.

POST /1.0/keys — add new API key

Expected name parameter is a unique name of the new API key, for example:

{
    "name": "my awesome key"
}

Example cURL request:

curl -X POST https://api.optidash.ai/1.0/keys -u MASTER_API_KEY: \
-H "Content-Type: application/json" \
-d '{
    "name": "my awesome key"
}'

The API will respond with 200 OK and the following data:

{
    "success": true,
    "name": "my awesome key",
    "key": "0UASk8hgjwSq1XetiVPLNyltNPvqJKAmBP8209Qn"
}

PUT /1.0/keys/:key — edit existing API key

This endpoint facilitates the renaming of an existing API key and requires a unique new name for the API key. By providing the desired new name, users can update the name associated with a specific API key, enhancing clarity and organization within their Optidash account.

{
    "name": "better name"
}

Example cURL request:

curl -X PUT https://api.optidash.ai/1.0/keys/API_KEY_TO_UPDATE -u MASTER_API_KEY: \
-H "Content-Type: application/json" \
-d '{
    "name":"better name"
}'

The API will respond with 200 OK and the following data:

{
    "success": true,
    "name": "better name",
    "key": "0UASk8hgjwSq1XetiVPLNyltNPvqJKAmBP8209Qn"
}

GET /1.0/keys/:key — get usage by API Key

This endpoint is used to query historical usage per API Key (defaults to last 90 days).

Example cURL request:

curl -X GET https://api.optidash.ai/1.0/keys/API_KEY -u MASTER_API_KEY:

The API will respond with 200 OK and the following data:

{
    "success": true,
    "results": [{
        "bucket": "2021-01-25T00:00:00.000Z",
        "volume": 0,
        "count": 0
    },
    {
        "bucket": "2021-01-26T00:00:00.000Z",
        "volume": 109500190,
        "count": 3333
    },
    {
        "bucket": "2021-01-27T00:00:00.000Z",
        "volume": 269640216,
        "count": 8994
    }
    ...
    ]
}

The GET /1.0/keys/:key endpoint also accepts three additional query parameters: from, to, and interval.

The from and to parameters control the date/time range in ISO-8601 format, while the interval parameter determines the granularity of the results. All requests to the /1.0/keys/:id endpoint must be authenticated with the master (primary) API key.

By default, the granularity (interval) is set to day if the interval parameter is omitted. However, it can be adjusted using the following values: minute, hour, day, week, and month.

It’s essential to use granularity wisely. For instance, if one queries for a maximum time range (90 days) and sets the interval to minute, the API will respond with 131487 time buckets.

Here’s an example cURL query that fulfills the request: “give me all usage data for the API key USER_API_KEY from 2021-01-19T00:00:00 to 2021-01-28T23:59:59 with hourly granularity”:

curl -X GET https://api.optidash.ai/1.0/keys/USER_API_KEY?interval=hour&from=2021-01-19T00:00:00&to=2021-01-28T23:59:59 -u MASTER_API_KEY:

Example response:

{
    "success": true,
    "results": [
        {
            "bucket": "2021-01-19T00:00:00.000Z",
            "volume": 51253,
            "count": 1
        },
        {
            "bucket": "2021-01-19T01:00:00.000Z",
            "volume": 0,
            "count": 0
        },
        {
            "bucket": "2021-01-19T02:00:00.000Z",
            "volume": 252849,
            "count": 3
        },
        ...
    ]
}

Wrapping Up

If you have any questions about the provisioning API or requests for additional features, please don’t hesitate to contact us anytime. We’re here to help and eager to assist you with any inquiries or feedback you may have.