Update API key

  • Updated on Mar 25, 2026
  • Published on Sep 2, 2025
Prev Next
Patch
/api_key/{api_key_id}

Update an existing API key

Security
HTTP
Type bearer

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

Path parameters
api_key_id
stringRequired

Supermetrics API key ID

Max length50
Pattern^[A-Za-z0-9_-]+$
Body parameters

API key update parameters for modifying permissions and settings

{
  "description": "Updated marketing team API key",
  "scope_names": [
    "ds_queries_read",
    "ds_queries_run",
    "table_groups_read",
    "team_lists_read"
  ],
  "allow_ips": [
    "192.168.1.0/24"
  ],
  "is_enabled": false,
  "behalf_of_user_id": null
}
object
description
string

Internal API key description

Max length1000
scope_names
Array of string

List of permission scopes for the API key

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", "dwh_transfers_read", "dwh_transfers_write", "table_groups_read", "table_groups_write", "team_lists_read", "team_lists_write", "team_read", "team_settings_read", "team_settings_write", "user_read" ]
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

behalf_of_user_id
string | null

Supermetrics user ID the API key identifies as. Use null to remove previously saved value.

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

API key updated successfully

Headers
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_-]+$
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
message
string

Error message

Max length255
description
string

Error description

Max length255
404

API Key Not Found

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_NOT_FOUND" ]
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
message
string

Error message

Max length255
description
string

Error description

Max length255
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
message
string

Error message

Max length255
description
string

Error description

Max length255
500

API Key Update 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*
object
error
string
Valid values[ "API_KEY_UPDATE_FAILED" ]
Max length100
message
string
Max length255

© Supermetrics 2025