Skip to main content
Beta ProductSQL Proxy is currently in beta. API endpoints may change.
Principals are Databricks identities that the proxy uses to execute queries. There are two types:
  • Users - Human users who authenticate with Databricks personal access tokens (PATs)
  • Service Principals - Machine identities that authenticate with OAuth client credentials
Both types can have warehouse access restrictions and default warehouse assignments.

​
Roles

Principals can be assigned one of two roles:
RoleDescription
standardDefault role. Can execute queries through the proxy using their assigned warehouses.
adminCan execute queries and manage Databricks warehouses (create, start, stop) on behalf of the proxy.
Only one principal should have the admin role per proxy deployment. If multiple admins exist, the proxy selects one at random for warehouse management operations, which may cause unexpected behavior.

​
Service Principals

​
List Service Principals

GET /admin/service-principals 
curl -X GET \
  -H "Authorization: Bearer <proxy-manager-token>" \
  https://sqlproxy.your-company.datafold.com/admin/service-principals

​
Get Service Principal

GET /admin/service-principals/{client_id} 
curl -X GET \
  -H "Authorization: Bearer <proxy-manager-token>" \
  https://sqlproxy.your-company.datafold.com/admin/service-principals/{client_id}

​
Create Service Principal

POST /admin/service-principals 
curl -X POST \
  -H "Authorization: Bearer <proxy-manager-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dbt-production",
    "client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "client_secret": "dapi...",
    "role": "standard",
    "default_warehouse": "abc123def4567890",
    "allowed_warehouses": ["abc123def4567890", "def456abc7890123"]
  }' \
  https://sqlproxy.your-company.datafold.com/admin/service-principals

​
Request Body

FieldTypeRequiredDescription
namestringYesDisplay name for the service principal
client_idstringYesOAuth client ID from Databricks (UUID format, e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)
client_secretstringNoOAuth client secret (starts with dapi)
rolestringNoRole: admin or standard (default: standard)
default_warehousestringNoDefault warehouse for routing
allowed_warehousesstring[]NoWarehouses this principal can access. Must include default_warehouse if both are specified.

​
Update Service Principal

PUT /admin/service-principals/{client_id} 
curl -X PUT \
  -H "Authorization: Bearer <proxy-manager-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dbt-prod-updated",
    "default_warehouse": "789012abc3456def",
    "allowed_warehouses": ["789012abc3456def", "def456abc7890123", "456def789012abc3"]
  }' \
  https://sqlproxy.your-company.datafold.com/admin/service-principals/{client_id}

​
Request Body

FieldTypeRequiredDescription
namestringNoDisplay name
client_secretstringNoOAuth client secret (starts with dapi)
rolestringNoRole: admin or standard
default_warehousestringNoReplaces default warehouse
allowed_warehousesstring[]NoReplaces all allowed warehouses

​
Delete Service Principal

DELETE /admin/service-principals/{client_id} 
curl -X DELETE \
  -H "Authorization: Bearer <proxy-manager-token>" \
  https://sqlproxy.your-company.datafold.com/admin/service-principals/{client_id}

​
Users

​
List Users

GET /admin/users 
curl -X GET \
  -H "Authorization: Bearer <proxy-manager-token>" \
  https://sqlproxy.your-company.datafold.com/admin/users

​
Get User

GET /admin/users/{user_id} 
curl -X GET \
  -H "Authorization: Bearer <proxy-manager-token>" \
  https://sqlproxy.your-company.datafold.com/admin/users/{user_id}

​
Create User

POST /admin/users 
curl -X POST \
  -H "Authorization: Bearer <proxy-manager-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "user_id": "4839201746582910",
    "token": "dapi...",
    "role": "standard",
    "default_warehouse": "def456abc7890123",
    "allowed_warehouses": ["def456abc7890123"]
  }' \
  https://sqlproxy.your-company.datafold.com/admin/users

​
Request Body

FieldTypeRequiredDescription
namestringYesDisplay name for the user
user_idstringYesDatabricks user ID (numeric, e.g., 4839201746582910)
tokenstringNoDatabricks personal access token (starts with dapi)
rolestringNoRole: admin or standard (default: standard)
default_warehousestringNoDefault warehouse for routing
allowed_warehousesstring[]NoWarehouses this user can access. Must include default_warehouse if both are specified.

​
Update User

PUT /admin/users/{user_id} 
curl -X PUT \
  -H "Authorization: Bearer <proxy-manager-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice (updated)",
    "default_warehouse": "abc123def4567890",
    "allowed_warehouses": ["abc123def4567890", "def456abc7890123"]
  }' \
  https://sqlproxy.your-company.datafold.com/admin/users/{user_id}

​
Request Body

FieldTypeRequiredDescription
namestringNoDisplay name
tokenstringNoDatabricks personal access token (starts with dapi)
rolestringNoRole: admin or standard
default_warehousestringNoReplaces default warehouse
allowed_warehousesstring[]NoReplaces all allowed warehouses

​
Delete User

DELETE /admin/users/{user_id} 
curl -X DELETE \
  -H "Authorization: Bearer <proxy-manager-token>" \
  https://sqlproxy.your-company.datafold.com/admin/users/{user_id}