> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# User Configs

> Manage your own Query Runner credential overrides, token refresh, and accessible metadata lookups through the Collate REST API

# User Configs

A user config layers the caller's credentials on top of a service's admin config for fields marked as user-configurable. Service-based lookups and updates use the caller's config, but a direct `userConfigId` lookup does not check ownership in Collate 2.0.2.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/queryRunner/user-configs` | Look up configs. `?userConfigId=` retrieves a config by ID. `?service=` retrieves the caller's config and status for one service. With no params, lists accessible services with enabled admin configs and their status, including entries with `userConfig: null`. Disabled services are omitted. |
| `POST` | `/v1/queryRunner/user-configs` | Create or update the caller's config for a service. |
| `PUT` | `/v1/queryRunner/user-configs?service={name}` | Update the caller's config. Restores masked secrets before validating. |
| `DELETE` | `/v1/queryRunner/user-configs?service={name}` | Delete the caller's config for a service. |
| `POST` | `/v1/queryRunner/user-configs/refresh-token` | Force an OAuth token refresh for the caller's config on `?service=`. |
| `POST` | `/v1/queryRunner/user-configs/test-connection` | Run a `SELECT 1` test connection using the caller's stored credentials. |
| `POST` | `/v1/queryRunner/user-configs/update-connection-status` | Called after a test-connection workflow completes, to record its result. |
| `GET` | `/v1/queryRunner/user-configs/accessible-roles` | Roles the caller's credentials can access on `?service=`. Snowflake and BigQuery only. |
| `GET` | `/v1/queryRunner/user-configs/accessible-databases` | Databases the caller's credentials can access on `?service=`. |
| `GET` | `/v1/queryRunner/user-configs/accessible-schemas` | Schemas within `?database=` that the caller's credentials can access on `?service=`. |

`POST`/`PUT` take `serviceName` (required) and `userAuthConfig`, shaped according to the service's auth type.

The three accessible-\* endpoints back the role, database, and schema pickers in Query Runner's UI. Use them to validate that a user's credentials can reach a given database or schema before running a query against it.

<Warning>
  In Collate 2.0.2, `GET /v1/queryRunner/user-configs?userConfigId=` can return another user's sanitized config metadata to an authenticated caller who knows the ID. Do not treat the ID or the returned metadata as private until ownership checks are enforced.
</Warning>

## Example

The following request creates a config for the calling user.

<RequestExample>
  ```bash Create your own config theme={null}
  curl -X POST "{base_url}/api/v1/queryRunner/user-configs" \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "serviceName": "snowflake_production",
      "userAuthConfig": { "authType": "Basic", "username": "jane", "password": "{password}" }
    }'
  ```

  ```bash List accessible databases theme={null}
  curl "{base_url}/api/v1/queryRunner/user-configs/accessible-databases?service=snowflake_production" \
    -H "Authorization: Bearer {access_token}"
  ```
</RequestExample>