Manage API keys

API keys are fixed authentication keys, used to access Supermetrics API.

Please note that this page is only available for general information purposes. Managing API keys requires an oAuth access token with appropriate permissions. Please contact us to manage your API keys for you.

• List API keys
• Get API key
• Add API key
• Update API key
• Supported scopes
• Restrictions
• Object reference
• Errors

List API keys

Response

HTTP 200 OK
{
    "meta": {
        "request_id": "WnjTGeKqOXTnkZQMbZCfVMdmswv2wAzx"
    },
    "data": [
        {
            "@type": "api_key",
            "api_key_id": "apk_2",
            "created_time": "2021-09-25T12:38:47+00:00",
            "description": "",
            "key_type": "none",
            "key_start": "api_H8TKlr...",
            "is_enabled": true,
            "behalf_of_user_info": null
        },
        {
            "@type": "api_key",
            "api_key_id": "apk_1",
            "created_time": "2021-08-04T04:16:19+00:00",
            "description": "My old API key",
            "key_type": "user",
            "key_start": "api_9Oz1n6...",
            "is_enabled": false,
            "behalf_of_user_info": {
                "@type": "user",
                "user_id": "usr_1",
                "email": "info@supermetrics.com"
            }
        }
    ]
}

Permissions

api_keys_read

Get API key

• api_key_id string
  Supermetrics API key ID
• show_key_value bool
  Optional. Show API key value as plain text into the response. Reading value is recorded to the audit logs.

Response

HTTP 200 OK
{
    "meta": {
        "request_id": "WnjTGeKqOXTnkZQMbZCfVMdmswv2wAzx"
    },
    "data": {
        "@type": "api_key",
        "api_key_id": "apk_2",
        "created_time": "2021-09-25T12:38:47+00:00",
        "description": "",
        "key_type": "none",
        "key_start": "api_H8TKlr...",
        "key_value": null,
        "scope_names": [
            "team_lists_write"
        ],
        "allow_ips": [
            "127.0.0.1"
        ],
        "is_enabled": true,
        "behalf_of_user_info": {
            "@type": "user",
            "user_id": "usr_1",
            "email": "info@supermetrics.com"
        }
    }
}

Permissions

api_keys_read

Add API key

Creating a new API key through this endpoint is recorded to the audit logs.

• key_type string
  Required. Type of key to create. Either query for shared API keys to show in Query Manager or user for private keys intended for one user.
• description string
  Optional. Internal API key description
• scope_names string | string[]
  Optional. List of permission scopes for the API key. Defaults to none. See scopes for more.
• allow_ips string | string[]
  Optional. List of fixed or CIDR formatted IP addresses allowed to use API key. Only IPv4 is supported.
• is_enabled bool
  Optional. Whether API key is enabled and can be used in requests. Defaults to true.
• behalf_of_user_id string
  Optional. Supermetrics user ID the API key identifies as. See restrictions for more.

Request

POST https://api.supermetrics.com/enterprise/v2/api_key
Authorization: Bearer <access token>
Content-Type: application/json

{
    "description": "My new API key",
    "behalf_of_user_id": "usr_1"
}

Response

Errors

API_KEY_ALLOW_IP_INVALID, API_KEY_LIMIT_EXCEEDED, API_KEY_SCOPE_NAME_INVALID, API_KEY_USER_INVALID

Permissions

api_keys_write

Update API key

• description string
  Optional. Internal API key description
• scope_names string | string[]
  Optional. List of permission scopes for the API key. Defaults to none. See scopes for more.
• allow_ips string | string[]
  Optional. List of fixed or CIDR formatted IP addresses allowed to use API key. Only IPv4 is supported.
• is_enabled bool
  Optional. Whether API key is enabled and can be used in requests. Defaults to true.
• behalf_of_user_id string
  Optional. Supermetrics user ID the API key identifies as. Use null to remove previously saved value. See restrictions for more.

Request

PATCH https://api.supermetrics.com/enterprise/v2/api_key/apk_3
Authorization: Bearer <access token>
Content-Type: application/json

{
    "description": "Old disabled API key",
    "is_enabled": false
}

Response

Errors

API_KEY_ALLOW_IP_INVALID, API_KEY_NOT_FOUND, API_KEY_SCOPE_NAME_INVALID, API_KEY_UPDATE_FAILED, API_KEY_USER_INVALID

Permissions

api_keys_write

Supported scopes

API keys can be given the following permission scopes to limit access to Supermetrics API.

Restrictions

• Please note that you are, by default, limited to total of 5 API keys. This number consists of both enabled and disabled API keys. Please contact us or your Supermetrics representative to get additional API keys.

• When an API key contains IP restrictions, it can no longer be used with previous version (v1) of the Supermetrics API. Please migrate any existing queries.

• When API key type is user and behalf_of_user has been specified, removing that user from your team will also disable the API key. Shared API keys will revert to their default behaviour – identifying as the first user in the team with OWNER or ADMIN role.

Object reference

api_key

user

Errors