--- icon: material/account-cog-outline --- The User Management API provides REST endpoints for managing user accounts and environments. !!! tip "Used by the MCP" The [MCP env and auth tools](/apps/mcp/) wrap these endpoints. See [Manage](/manage/) for the conceptual guide. | Deployment | API Endpoint | |------------|--------------| | **Cloud (SaaS)** | `https://prometheus.log10x.com` | | **Self-Hosted** | Your configured endpoint (set `LOG10X_API_BASE`) | !!! note "One endpoint for user management and metrics" User management and Prometheus queries share a single base endpoint and API Gateway. The MCP and console default to `https://prometheus.log10x.com` (override with `LOG10X_API_BASE`). `api.log10x.com` is an alias that resolves to the same gateway. Authenticate using a 10x API key via the `X-10X-Auth` header. ## Authentication All endpoints require authentication via the `X-10X-Auth` header. The header accepts two formats: | Format | Description | |--------|-------------| | `X-10X-Auth: ` | Uses the default environment | | `X-10X-Auth: /` | Specifies a target environment | ??? tenx-api "Authentication Header Examples" ``` X-10X-Auth: your-api-key-here X-10X-Auth: your-api-key-here/00000000-0000-0000-0000-000000000000 ``` Your API key determines your identity and permission level (`OWNER`, `WRITE`, or `READ`) for the target environment. --- ## User Endpoints ### Get Current User Retrieves information about the authenticated user including their environments and metadata. | Property | Value | |----------|-------| | **Endpoint** | `GET /api/v1/user` | ??? tenx-api "Request Example" ``` console curl -s -H "X-10X-Auth: " \ "https://prometheus.log10x.com/api/v1/user" ``` ??? tenx-api "Response (200 OK)" ``` json { "user": { "username": "user@example.com", "licenses": 1, "environments": [ { "is_default": true, "name": "Production", "owner": "user@example.com", "env_id": "00000000-0000-0000-0000-000000000000", "permissions": "OWNER" } ], "metadata": { "company": "Acme Inc" } } } ``` --- ### Update User Updates the authenticated user's metadata. | Property | Value | |----------|-------| | **Endpoint** | `POST /api/v1/user` | | **Content-Type** | `application/json` | ??? tenx-api "Request Example" ``` console curl -s -X POST \ -H "X-10X-Auth: " \ -H "Content-Type: application/json" \ -d '{"metadata": {"company": "New Company Name"}}' \ "https://prometheus.log10x.com/api/v1/user" ``` **Request Body:** | Field | Type | Description | |-------|------|-------------| | `metadata` | object | Custom user metadata key-value pairs | ??? tenx-api "Response (200 OK)" ``` json { "user": { "username": "user@example.com", "licenses": 1, "environments": [...], "metadata": { "company": "New Company Name" } } } ``` --- ### Rotate API Key Generates a new API key for the authenticated user. The previous key is **invalidated immediately** on success. Every other client (other MCP hosts, the console on a different machine, scripts, etc.) holding the old key will start receiving `401 Unauthorized` on the next request. | Property | Value | |----------|-------| | **Endpoint** | `POST /api/v1/user/rotate-key` | | **Request Body** | None (empty) | !!! note "Save the new key from the response" The response body contains the freshly-minted `api_key`. Capture it from there for any scripted or automated flow. If you miss it, mint a replacement with `log10x_rotate_api_key`; the old key is invalidated the instant the new one exists. !!! note "New key takes effect within seconds" The old key stops working immediately, but the new key may need up to a few seconds before it is accepted on every request. If the first call right after rotation fails with `401` or `403`, retry once after a short wait. Scripted callers should wrap the first post-rotation request in a brief retry loop. !!! note "Demo users cannot rotate" Demo accounts (`user_type: "Demo"` in `app_metadata`) receive `403 Forbidden`. ??? tenx-api "Request Example" ``` console curl -s -X POST \ -H "X-10X-Auth: " \ "https://prometheus.log10x.com/api/v1/user/rotate-key" ``` ??? tenx-api "Response (200 OK)" ``` json { "user": { "username": "user@example.com", "licenses": 1, "environments": [ { "is_default": true, "name": "Production", "owner": "user@example.com", "env_id": "00000000-0000-0000-0000-000000000000", "permissions": "OWNER" } ], "metadata": { "company": "Acme Inc" } }, "api_key": "11111111-2222-3333-4444-555555555555" } ``` The `api_key` field is the **new** key. Update every place where the old key is configured (MCP host configs, scripts, CI secrets, etc.). Anything still using the previous value will start receiving `401`. ??? tenx-api "Response (403 Forbidden)" ``` json { "error": "Demo users cannot rotate API key" } ``` --- ## Environment Endpoints ### Create Environment Creates a new environment for the authenticated user. | Property | Value | |----------|-------| | **Endpoint** | `POST /api/v1/user/env` | | **Content-Type** | `application/json` | ??? tenx-api "Request Example" ``` console curl -s -X POST \ -H "X-10X-Auth: " \ -H "Content-Type: application/json" \ -d '{"name": "Staging", "is_default": false}' \ "https://prometheus.log10x.com/api/v1/user/env" ``` **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Unique name for the environment | | `is_default` | boolean | No | Set as the default environment | ??? tenx-api "Response (200 OK)" ``` json { "user": { "username": "user@example.com", "licenses": 1, "environments": [ { "is_default": true, "name": "Production", "owner": "user@example.com", "env_id": "00000000-0000-0000-0000-000000000000", "permissions": "OWNER" }, { "is_default": false, "name": "Staging", "owner": "user@example.com", "env_id": "11111111-1111-1111-1111-111111111111", "permissions": "OWNER" } ], "metadata": {} } } ``` --- ### Update Environment Updates an existing environment. You must be the owner of the environment. | Property | Value | |----------|-------| | **Endpoint** | `PUT /api/v1/user/env` | | **Content-Type** | `application/json` | ??? tenx-api "Request Example" ``` console curl -s -X PUT \ -H "X-10X-Auth: " \ -H "Content-Type: application/json" \ -d '{"env_id": "11111111-1111-1111-1111-111111111111", "name": "QA Environment", "is_default": false}' \ "https://prometheus.log10x.com/api/v1/user/env" ``` **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `env_id` | string | Yes | UUID of the environment to update | | `name` | string | No | New name (provide `name`, `is_default`, or both) | | `is_default` | boolean | No | Set as the default environment | ??? tenx-api "Response (200 OK)" ``` json { "user": { "username": "user@example.com", "licenses": 1, "environments": [ { "is_default": false, "name": "QA Environment", "owner": "user@example.com", "env_id": "11111111-1111-1111-1111-111111111111", "permissions": "OWNER" } ], "metadata": {} } } ``` --- ### Delete Environment Deletes an environment. You must be the owner of the environment. | Property | Value | |----------|-------| | **Endpoint** | `DELETE /api/v1/user/env` | | **Content-Type** | `application/json` | ??? tenx-api "Request Example" ``` console curl -s -X DELETE \ -H "X-10X-Auth: " \ -H "Content-Type: application/json" \ -d '{"env_id": "11111111-1111-1111-1111-111111111111"}' \ "https://prometheus.log10x.com/api/v1/user/env" ``` **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `env_id` | string | Yes | UUID of the environment to delete | ??? tenx-api "Response (200 OK)" ``` json { "user": { "username": "user@example.com", "licenses": 1, "environments": [ { "is_default": true, "name": "Production", "owner": "user@example.com", "env_id": "00000000-0000-0000-0000-000000000000", "permissions": "OWNER" } ], "metadata": {} } } ``` --- ## Data Models ### UserInfo The user object returned by all API endpoints. | Field | Type | Description | |-------|------|-------------| | `username` | string | User's email address | | `licenses` | number | Number of licensed environments | | `environments` | array | List of [Environment](#environment) objects | | `metadata` | object | Custom user metadata | ### Environment Represents a 10x environment within a user's account. | Field | Type | Description | |-------|------|-------------| | `env_id` | string | Unique UUID identifier | | `name` | string | Display name | | `owner` | string | Owner's email address | | `is_default` | boolean | Whether this is the default environment | | `permissions` | string | Access level: `OWNER`, `WRITE`, or `READ` | **Permission Levels:** | Permission | Description | |------------|-------------| | `OWNER` | Full access including create, update, and delete | | `WRITE` | Can write and update data | | `READ` | Read-only access | --- ## Error Responses All endpoints return standard HTTP status codes with JSON error bodies. | Status | Description | Common Causes | |--------|-------------|---------------| | `400` | Bad Request | Missing required fields, invalid JSON | | `401` | Unauthorized | Invalid API key, insufficient permissions | | `404` | Not Found | Environment does not exist | | `409` | Conflict | Duplicate environment name | | `500` | Internal Server Error | Service unavailable | ??? tenx-api "Error Response Example" ``` json { "error": "environment name already exists for this owner" } ``` --- ## Examples ??? tenx-api "Full Workflow: Create and Configure Environment" ``` console # 1. Get current user info curl -s -H "X-10X-Auth: " \ "https://prometheus.log10x.com/api/v1/user" # 2. Create a new staging environment curl -s -X POST \ -H "X-10X-Auth: " \ -H "Content-Type: application/json" \ -d '{"name": "Staging", "is_default": false}' \ "https://prometheus.log10x.com/api/v1/user/env" # 3. Use the new environment's env_id in subsequent API calls curl -s -H "X-10X-Auth: /11111111-1111-1111-1111-111111111111" \ "https://prometheus.log10x.com/api/v1/query?query=tenx_pipeline_up" ``` ??? tenx-api "Update User Metadata" ``` console curl -s -X POST \ -H "X-10X-Auth: " \ -H "Content-Type: application/json" \ -d '{ "metadata": { "company": "Acme Corporation", "team": "Platform Engineering", "notifications": true } }' \ "https://prometheus.log10x.com/api/v1/user" ```