> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Api Key > Create a new API key for a user. ## OpenAPI ````yaml post /v1/organizations/users/{user_email}/api-keys openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/organizations/users/{user_email}/api-keys: post: tags: - Organization API Keys summary: Create Api Key description: Create a new API key for a user. operationId: create_api_key_v1_organizations_users__user_email__api_keys_post parameters: - name: user_email in: path required: true schema: type: string title: User Email requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/APIKeyCreateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/APIKeyCreateResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: APIKeyCreateRequest: properties: name: type: string maxLength: 100 minLength: 1 title: Name description: Human-friendly key label shown in dashboards. description: anyOf: - type: string maxLength: 500 - type: 'null' title: Description description: Optional description explaining the key's purpose. permissions: items: $ref: '#/components/schemas/Permission' type: array title: Permissions description: >- Set of permissions granted to the API key. Defaults to full read/write/delete access. Restrict explicitly when creating scoped keys. scopes: anyOf: - items: $ref: '#/components/schemas/ResourceScope-Input' type: array - type: 'null' title: Scopes description: Optional resource scope restrictions applied to the key. rate_limit_override: anyOf: - type: integer minimum: 1 - type: 'null' title: Rate Limit Override description: >- Per-key requests-per-minute override (defaults to plan limit when absent). expires_at: anyOf: - type: string format: date-time - type: 'null' title: Expires At description: Optional UTC timestamp when the key automatically expires. principal_id: anyOf: - type: string - type: 'null' title: Principal Id description: >- End-user identifier for document-level ACL. When set, the key becomes user-scoped and all document reads are automatically filtered to documents the principal has access to. This represents an end-user in your application, NOT an org user. type: object required: - name title: APIKeyCreateRequest description: Payload for creating a new API key. examples: - description: Service account for ingestion pipeline name: backend-service permissions: - read - write rate_limit_override: 120 - name: analytics-read permissions: - read scopes: - operations: - read_data resource_id: ns_reporting resource_type: namespace APIKeyCreateResponse: properties: key_id: type: string title: Key Id description: Public identifier for the API key. key_hash: type: string title: Key Hash description: SHA-256 hash of the plaintext key. key_prefix: anyOf: - type: string maxLength: 64 - type: 'null' title: Key Prefix description: >- 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. examples: - sk_abc123... - sk_xyz789... key_type: $ref: '#/components/schemas/APIKeyType' description: >- Type of API key. STANDARD for regular organization keys, MARKETPLACE_SUBSCRIPTION for marketplace subscription access tokens. default: standard subscription_id: anyOf: - type: string - type: 'null' title: Subscription Id description: >- Marketplace subscription ID if this is a marketplace subscription key. Only set when key_type is MARKETPLACE_SUBSCRIPTION. internal_id: type: string title: Internal Id description: Organization internal identifier. organization_id: anyOf: - type: string - type: 'null' title: Organization Id description: Organization public identifier (denormalized). user_id: type: string title: User Id description: Identifier of the user who owns the key. name: type: string title: Name description: Human-friendly key label. description: type: string title: Description description: Optional description explaining the key usage. default: '' permissions: items: $ref: '#/components/schemas/Permission' type: array title: Permissions description: Permissions granted to the key. scopes: items: $ref: '#/components/schemas/ResourceScope-Output' type: array title: Scopes description: Resource-level scopes restricting the key. rate_limit_override: anyOf: - type: integer - type: 'null' title: Rate Limit Override description: Optional per-key rate limit override in requests per minute. status: $ref: '#/components/schemas/KeyStatus' description: Lifecycle status of the key (active, revoked, expired). default: active expires_at: anyOf: - type: string format: date-time - type: 'null' title: Expires At description: UTC timestamp when the key automatically expires. last_used_at: anyOf: - type: string format: date-time - type: 'null' title: Last Used At description: UTC timestamp of the last successful request using the key. created_at: type: string format: date-time title: Created At description: UTC timestamp when the key was created. created_by: anyOf: - type: string - type: 'null' title: Created By description: User identifier that created the key. revoked_at: anyOf: - type: string format: date-time - type: 'null' title: Revoked At description: UTC timestamp when the key was revoked (if applicable). revoked_by: anyOf: - type: string - type: 'null' title: Revoked By description: User identifier that revoked the key (if applicable). allowed_origins: anyOf: - items: type: string type: array - type: 'null' title: Allowed Origins description: >- Optional list of allowed HTTP origins for this API key. When set, requests must include an Origin header matching one of these values. Supports exact matches (e.g., 'https://docs.example.com') and wildcard subdomains (e.g., 'https://*.example.com'). Only enforced for browser requests (defense-in-depth, not a security boundary). Null means no origin restriction. examples: - - https://docs.example.com - https://*.example.com principal_id: anyOf: - type: string - type: 'null' title: Principal Id description: >- End-user identifier for document-level ACL (row-level security). When set, this key is user-scoped: all document reads are automatically filtered to documents the principal owns or has been granted access to. This represents an end-user in your application, NOT an org user. key: type: string title: Key type: object required: - key_hash - internal_id - user_id - name - key title: APIKeyCreateResponse description: API key response including the plaintext secret. examples: - created_at: '2025-01-01T00:00:00Z' created_by: usr_admin description: Service account for ingestion internal_id: int_x1y2z3 key_hash: 2c26b46b68ffc68ff99b453c1d304134 key_id: key_a1b2c3d4e5f6g7h key_prefix: sk_abc123... name: backend-service organization_id: org_demo123 permissions: - read - write scopes: [] status: active user_id: usr_a1b2c3d4e5f6g7h ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Permission: type: string enum: - read - write - delete - admin title: Permission description: |- 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. ResourceScope-Input: properties: resource_type: $ref: '#/components/schemas/ResourceType-Input' description: >- Resource type this scope governs. Use ResourceType enum values to scope a key to namespaces, collections, clusters, etc. resource_id: type: string maxLength: 100 minLength: 1 title: Resource Id description: >- Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '*' or 'ns_customer_*'. operations: anyOf: - items: $ref: '#/components/schemas/NamespaceOperation' type: array - type: 'null' title: Operations description: >- Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list. type: object required: - resource_type - resource_id title: ResourceScope description: Fine-grained restriction applied to an API key. examples: - description: Full namespace access (data + infrastructure) resource_id: ns_production resource_type: namespace - description: Analytics-only access in namespace operations: - read_data - execute_retriever resource_id: ns_customer_123 resource_type: namespace - description: Specific collection only resource_id: col_products resource_type: collection APIKeyType: type: string enum: - standard - marketplace_subscription - retriever - user_scoped - session title: APIKeyType description: >- Type of API key determining its purpose and scope. - STANDARD: Regular organization API key with standard permissions. - MARKETPLACE_SUBSCRIPTION: Special key generated for marketplace subscriptions, allowing cross-org access to specific marketplace retrievers. - RETRIEVER: Per-retriever API key scoped to execute a specific retriever. Only the retriever owner can create these keys. Prefix: ret_sk_ - SESSION: Short-lived key minted by Studio on each login to back the authenticated UI. Hidden from the user-facing key list endpoints. ResourceScope-Output: properties: resource_type: $ref: '#/components/schemas/shared__organizations__enums__ResourceType' description: >- Resource type this scope governs. Use ResourceType enum values to scope a key to namespaces, collections, clusters, etc. resource_id: type: string maxLength: 100 minLength: 1 title: Resource Id description: >- Identifier or pattern for the resource. Accepts a literal ID (e.g. 'ns_production') or wildcard forms such as '*' or 'ns_customer_*'. operations: anyOf: - items: $ref: '#/components/schemas/NamespaceOperation' type: array - type: 'null' title: Operations description: >- Subset of operations allowed within the scope. When omitted the key may perform any operation permitted by its Permission list. type: object required: - resource_type - resource_id title: ResourceScope description: Fine-grained restriction applied to an API key. examples: - description: Full namespace access (data + infrastructure) resource_id: ns_production resource_type: namespace - description: Analytics-only access in namespace operations: - read_data - execute_retriever resource_id: ns_customer_123 resource_type: namespace - description: Specific collection only resource_id: col_products resource_type: collection KeyStatus: type: string enum: - active - revoked - expired title: KeyStatus description: >- Lifecycle state of an API key. Status determines whether an API key can be used for authentication: - ACTIVE: Key is valid and can be used for API requests. Last_used_at timestamp is updated on each successful authentication. - REVOKED: Key has been manually revoked by an admin or user. Cannot be reactivated. A new key must be created instead. - EXPIRED: Key has passed its expires_at timestamp. Automatically set by the authentication system. Cannot be reactivated. ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ResourceType-Input: type: string enum: - organization - user - api_key - namespace - collection - bucket - retriever - cluster - taxonomy - storage_connection - alert - annotation - secret - webhook title: ResourceType description: |- Resource surfaces supported by scoped API keys and audit events. These resource types can be used in: - API key scopes to restrict access to specific resources - Audit logs to identify what type of resource was affected - Permission systems to grant/deny access to resource categories Resource hierarchy: ORGANIZATION -> USER, API_KEY, STORAGE_CONNECTION NAMESPACE -> COLLECTION, BUCKET, RETRIEVER, CLUSTER, TAXONOMY Resource types: - ORGANIZATION: Top-level tenant entity - USER: Organization member with authentication credentials - API_KEY: Authentication token for programmatic access - NAMESPACE: Isolated environment for data and compute resources - COLLECTION: Vector database collection for searchable documents - BUCKET: Object storage container for raw files - RETRIEVER: Configured search/retrieval pipeline - CLUSTER: Ray compute cluster for distributed processing - TAXONOMY: Hierarchical classification system for documents - STORAGE_CONNECTION: External storage provider integration NamespaceOperation: type: string enum: - 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 title: NamespaceOperation description: >- 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 shared__organizations__enums__ResourceType: type: string enum: - organization - user - api_key - namespace - collection - bucket - retriever - cluster - taxonomy - storage_connection - alert - annotation - secret - webhook title: ResourceType description: |- Resource surfaces supported by scoped API keys and audit events. These resource types can be used in: - API key scopes to restrict access to specific resources - Audit logs to identify what type of resource was affected - Permission systems to grant/deny access to resource categories Resource hierarchy: ORGANIZATION -> USER, API_KEY, STORAGE_CONNECTION NAMESPACE -> COLLECTION, BUCKET, RETRIEVER, CLUSTER, TAXONOMY Resource types: - ORGANIZATION: Top-level tenant entity - USER: Organization member with authentication credentials - API_KEY: Authentication token for programmatic access - NAMESPACE: Isolated environment for data and compute resources - COLLECTION: Vector database collection for searchable documents - BUCKET: Object storage container for raw files - RETRIEVER: Configured search/retrieval pipeline - CLUSTER: Ray compute cluster for distributed processing - TAXONOMY: Hierarchical classification system for documents - STORAGE_CONNECTION: External storage provider integration ````