Update Api Key

curl --request PATCH \
  --url https://api.mixpeek.com/v1/organizations/users/{user_email}/api-keys/{key_name} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "permissions": [
    "read"
  ],
  "scopes": [
    {
      "resource_type": "organization",
      "resource_id": "<string>",
      "operations": [
        "read_data"
      ]
    }
  ],
  "rate_limit_override": 2,
  "expires_at": "2023-11-07T05:31:56Z",
  "status": "active"
}
'

{
  "key_hash": "<string>",
  "internal_id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "key_id": "<string>",
  "key_prefix": "sk_abc123...",
  "organization_id": "<string>",
  "description": "",
  "permissions": [
    "read"
  ],
  "scopes": [
    {
      "resource_type": "organization",
      "resource_id": "<string>",
      "operations": [
        "read_data"
      ]
    }
  ],
  "rate_limit_override": 123,
  "status": "active",
  "expires_at": "2023-11-07T05:31:56Z",
  "last_used_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "revoked_by": "<string>"
}

PATCH

organizations

users

{user_email}

api-keys

{key_name}

Update Api Key

curl --request PATCH \
  --url https://api.mixpeek.com/v1/organizations/users/{user_email}/api-keys/{key_name} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "permissions": [
    "read"
  ],
  "scopes": [
    {
      "resource_type": "organization",
      "resource_id": "<string>",
      "operations": [
        "read_data"
      ]
    }
  ],
  "rate_limit_override": 2,
  "expires_at": "2023-11-07T05:31:56Z",
  "status": "active"
}
'

{
  "key_hash": "<string>",
  "internal_id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "key_id": "<string>",
  "key_prefix": "sk_abc123...",
  "organization_id": "<string>",
  "description": "",
  "permissions": [
    "read"
  ],
  "scopes": [
    {
      "resource_type": "organization",
      "resource_id": "<string>",
      "operations": [
        "read_data"
      ]
    }
  ],
  "rate_limit_override": 123,
  "status": "active",
  "expires_at": "2023-11-07T05:31:56Z",
  "last_used_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": "<string>",
  "revoked_at": "2023-11-07T05:31:56Z",
  "revoked_by": "<string>"
}

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Path Parameters

user_email

string

required

key_name

string

required

Body

application/json

Partial update payload for an API key.

name

string | null

New key label.

Required string length: 1 - 100

description

string | null

Updated description for the key.

Maximum string length: 500

permissions

enum<string>[] | null

Replace existing permissions with the provided list.

Simplified API key permissions.

This four-value enum replaces the legacy 16-permission model. Keep usage simple: prefer the least privileged option that satisfies the workflow.

Hierarchy (strongest -> weakest): ADMIN > DELETE > WRITE > READ.

Available options:

read,

write,

delete,

admin

scopes

ResourceScope · object[] | null

Replace existing scopes. Use empty list for global access.

Show child attributes

scopes.resource_type

enum<string>

required

Resource type this scope governs. Use ResourceType enum values to scope a key to namespaces, collections, clusters, etc.

Available options:

organization,

user,

api_key,

namespace,

collection,

bucket,

retriever,

cluster,

storage_connection

scopes.resource_id

string

required

Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '' or 'ns_customer_'.

Required string length: 1 - 100

scopes.operations

enum<string>[] | null

Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list.

Granular operations that can be scoped inside a namespace.

These operations are used to define fine-grained permissions for API keys and users within specific namespaces. Operations can be granted individually or in combination to implement least-privilege access control.

Data operations: - READ_DATA: View and search documents, retrieve objects from buckets - WRITE_DATA: Create and update documents, upload objects to buckets - DELETE_DATA: Remove documents and objects permanently

Retrieval operations: - EXECUTE_RETRIEVER: Run search queries using configured retrievers - CREATE_RETRIEVER: Define new retrieval pipelines with custom stages - DELETE_RETRIEVER: Remove retrieval pipeline configurations

Job execution: - EXECUTE_JOB: Trigger ingestion pipelines and batch processing jobs - CANCEL_JOB: Abort running jobs before completion

Cluster management (Ray infrastructure): - CREATE_CLUSTER: Provision new Ray compute clusters - DELETE_CLUSTER: Tear down existing compute clusters - MODIFY_CLUSTER: Scale or reconfigure running clusters

Infrastructure configuration: - MODIFY_INFRASTRUCTURE: Change namespace settings, storage connections - MANAGE_PERMISSIONS: Grant and revoke user access within the namespace

Examples: - Read-only access: [READ_DATA, EXECUTE_RETRIEVER] - Data engineer access: [READ_DATA, WRITE_DATA, EXECUTE_JOB] - Full namespace admin: All operations granted

Available options:

read_data,

write_data,

delete_data,

execute_retriever,

create_retriever,

delete_retriever,

execute_job,

cancel_job,

create_cluster,

delete_cluster,

modify_cluster,

modify_infrastructure,

manage_permissions

rate_limit_override

integer | null

Updated per-key rate limit override.

Required range: x >= 1

expires_at

string<date-time> | null

New expiration timestamp. Use null to remove expiration.

status

enum<string> | null

Manually set key status (e.g. revoke).

Available options:

active,

revoked,

expired

Response

Successful Response

API key document stored in MongoDB.

key_hash

string

required

SHA-256 hash of the plaintext key.

internal_id

string

required

Organization internal identifier.

user_id

string

required

Identifier of the user who owns the key.

name

string

required

Human-friendly key label.

key_id

string

Public identifier for the API key.

key_prefix

string | null

Visible prefix of the API key for user identification (e.g., 'sk_abc123...'). Shows the first 10 characters of the plaintext key to help users identify which key is which in lists, without exposing the full secret. This follows industry best practices from GitHub, Stripe, and AWS. Generated automatically for new keys. Older keys may not have this field.

Required string length: 10 - 13

Example:

"sk_abc123..."

organization_id

string | null

Organization public identifier (denormalized).

description

string

default:""

Optional description explaining the key usage.

permissions

enum<string>[]

Permissions granted to the key (least privilege recommended).

Simplified API key permissions.

This four-value enum replaces the legacy 16-permission model. Keep usage simple: prefer the least privileged option that satisfies the workflow.

Hierarchy (strongest -> weakest): ADMIN > DELETE > WRITE > READ.

Available options:

read,

write,

delete,

admin

scopes

ResourceScope · object[]

Resource-level scopes restricting the key.

Show child attributes

scopes.resource_type

enum<string>

required

Resource type this scope governs. Use ResourceType enum values to scope a key to namespaces, collections, clusters, etc.

Available options:

organization,

user,

api_key,

namespace,

collection,

bucket,

retriever,

cluster,

storage_connection

scopes.resource_id

string

required

Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '' or 'ns_customer_'.

Required string length: 1 - 100

scopes.operations

enum<string>[] | null

Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list.

Granular operations that can be scoped inside a namespace.

Job execution: - EXECUTE_JOB: Trigger ingestion pipelines and batch processing jobs - CANCEL_JOB: Abort running jobs before completion

Infrastructure configuration: - MODIFY_INFRASTRUCTURE: Change namespace settings, storage connections - MANAGE_PERMISSIONS: Grant and revoke user access within the namespace

Examples: - Read-only access: [READ_DATA, EXECUTE_RETRIEVER] - Data engineer access: [READ_DATA, WRITE_DATA, EXECUTE_JOB] - Full namespace admin: All operations granted

Available options:

read_data,

write_data,

delete_data,

execute_retriever,

create_retriever,

delete_retriever,

execute_job,

cancel_job,

create_cluster,

delete_cluster,

modify_cluster,

modify_infrastructure,

manage_permissions

rate_limit_override

integer | null

Optional per-key rate limit override in requests per minute.

status

enum<string>

default:active

Lifecycle status of the key (active, revoked, expired).

Available options:

active,

revoked,

expired

expires_at

string<date-time> | null

UTC timestamp when the key automatically expires.

last_used_at

string<date-time> | null

UTC timestamp of the last successful request using the key.

created_at

string<date-time>

UTC timestamp when the key was created.

created_by

string | null

User identifier that created the key.

revoked_at

string<date-time> | null

UTC timestamp when the key was revoked (if applicable).

revoked_by

string | null

User identifier that revoked the key (if applicable).

Create Api Key Rotate Api Key

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Update Api Key

Headers

Path Parameters

Body

Response