Create API key

  • Updated on Dec 16, 2025
  • Published on Sep 2, 2025
Prev Next
Post
/api_keys

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

Security
HTTP
Type bearer

Bearer token authentication. Include the token in the Authorization header: Authorization: Bearer <your-token>

Body parameters

API key creation parameters including type, permissions, and access controls

{
  "key_type": "query",
  "description": "Marketing team API key",
  "scope_names": [
    "ds_queries_read",
    "ds_queries_run",
    "table_groups_read"
  ],
  "allow_ips": [
    "192.168.1.100",
    "10.0.0.0/24"
  ],
  "is_enabled": true,
  "behalf_of_user_id": "user_123456"
}
object
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.

Valid values[ "query", "user" ]
description
string

Internal API key description

Max length1000
scope_names
Array of string

List of permission scopes for the API key. Defaults to none.

Max items100
string
Valid values[ "ds_accounts_read", "ds_login_links_read", "ds_login_links_write", "ds_logins_read", "ds_logins_write", "ds_queries_read", "ds_queries_run", "table_groups_read", "table_groups_write", "team_lists_read", "team_lists_write", "team_settings_read", "team_settings_write" ]
allow_ips
Array of string

List of fixed or CIDR formatted IP addresses allowed to use API key. Only IPv4 is supported.

Max items100
string
Max length255
Pattern^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\/([0-9]|[1-2][0-9]|3[0-2]))?$
is_enabled
boolean

Whether API key is enabled and can be used in requests

Defaulttrue
behalf_of_user_id
string | null

Supermetrics user ID the API key identifies as

Max length50
Pattern^[A-Za-z0-9_-]+$
Responses
201

API key created successfully

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Location
string
API URL of the created item
Max length255
Exampleitems/{id}
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
data
object (ApiKey)
@type
string
Valid values[ "api_key" ]
api_key_id
string

Supermetrics API key ID

Max length50
Pattern^[A-Za-z0-9_-]+$
created_time
string (date-time)

ISO 8601 datetime for when API key was created

Max length50
description
string

Internal API key description

Max length1000
key_type
string

Type of API key

Max length50
key_start
string

First 10 characters from the API key value

Max length50
Pattern^[A-Za-z0-9_-]+$
key_value
string

API key value as plain text, when requested. Defaults to null.

Max length255
Pattern^[A-Za-z0-9_-]+$
scope_names
Array of string

List of permission scopes for the API key

Max items100
string
Max length100
allow_ips
Array of string

List of fixed or CIDR formatted IP addresses allowed to use API key

Max items100
string
Max length255
Pattern^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\/([0-9]|[1-2][0-9]|3[0-2]))?$
is_enabled
boolean

Whether API key is enabled and can be used in requests

behalf_of_user_info
object (User)
@type
string
Valid values[ "user" ]
user_id
string

Supermetrics user ID

Max length50
Pattern^[A-Za-z0-9_-]+$
email
string (email)

Supermetrics user email

Max length255
400

API Key Error

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
object
error
string
Valid values[ "API_KEY_ALLOW_IP_INVALID", "API_KEY_SCOPE_NAME_INVALID", "API_KEY_USER_INVALID" ]
Max length100
message
string
Max length255
401

Unauthorized - invalid or missing authentication

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
403

API Key Limit Exceeded

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
object
error
string
Valid values[ "API_KEY_LIMIT_EXCEEDED" ]
Max length100
message
string
Max length255
422

Unprocessable Entity - request validation failed

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
429

Too Many Requests - rate limit exceeded

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Retry-After
integer
Number of seconds to wait before making another request
Minimum1
Maximum3600
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.
500

Internal Server Error - unexpected server error

Headers
Content-Type
string
HTTP response content type
Valid values[ "application/json" ]
Max length255
Exampleapplication/json
X-RateLimit-Limit
integer
Request limit per hour
Minimum1
Maximum10000
Example100
X-RateLimit-Remaining
integer
Remaining requests in current window
Minimum0
Maximum10000
Example49
Access-Control-Allow-Origin
string
CORS header
Valid values[ "*" ]
Max length255
Example*
Expand All
object
meta
object (ResponseMeta)
request_id
string

API request ID

Max length50
Pattern^[A-Za-z0-9_-]+$
error
object (Error)
code
string

Error code

Max length100
ExampleACCESS_TOKEN_INVALID
message
string

Error message

Max length255
ExampleInvalid Access Token
description
string

Error description

Max length255
ExampleProvided access token is either missing, invalid or expired.