Authentication and configuration

zsql authenticates every request with Authorization: Bearer <key>. The key comes from an environment variable or a small YAML file in the project; the server URL comes from a flag, an environment variable, the same files or project.yml.

Keys

Keys are created in the console at https://app.0sql.io.

KindPrefixForCan
Personal keyzsk_People and CIEverything its user may do: deploy, test, remove, query
Query keyzqk_ApplicationsRead only: sql, explain, explore, fields, tables and the branch summary, on the projects and branches it is granted

Each key’s secret is shown once, 44 characters long, and listed afterwards by its first 12 characters. zsql works with either kind, but zsql deploy with a query key answers Forbidden: query keys are read only; deploy with your personal key. Members, roles, grants and rotation are on Accounts.

zsql auth

zsql auth --api-key KEY [--server URL]

Writes the key (and the server, if given) into .zsql in the project directory, replacing any existing line for the same key. The file is created with mode 0600 and is in the .gitignore that zsql init wrote.

$ zsql auth --api-key zsk_1kJ9... --server https://app.0sql.io
saved to /home/you/tpcds/.zsql

The file:

# zsql local configuration: api key and server. Do not commit.
api_key: zsk_1kJ9...
server: https://app.0sql.io

zsql auth must run inside a project (or with --project DIR), because the file is per project. One project can hold one key at a time; switch keys by running it again.

Environment variables

ZSQL_API_KEY wins over every file. It is the right place for a key in CI and in any shell where you do not want a file on disk:

export ZSQL_API_KEY=zsk_1kJ9...
zsql deploy --branch main

ZSQL_SERVER sets the server the same way.

~/.zsql/config

The same YAML keys as .zsql (api_key, server), read when the project file has no value for them. Put a personal key there once and every project on the machine uses it unless its own .zsql says otherwise. The repl keeps its history beside it, in ~/.zsql/history.

Resolution order

The API key:

  1. ZSQL_API_KEY
  2. api_key: in .zsql in the project directory, or .strata if .zsql does not exist
  3. api_key: in ~/.zsql/config

The server:

  1. --server URL
  2. ZSQL_SERVER
  3. server: in .zsql (or .strata) in the project directory, then in ~/.zsql/config
  4. server: in project.yml
  5. http://127.0.0.1:3699, a local development default

Because of step 5, set the server once: zsql auth --api-key KEY --server https://app.0sql.io, or export ZSQL_SERVER=https://app.0sql.io. A trailing / is trimmed.

.strata is read only when .zsql is absent. It exists so a project that already has a .strata file with an api_key works without a second file; new projects use .zsql.

zsql health

zsql health

Resolves the server the same way and calls its unauthenticated liveness route. No key needed.

$ zsql health
https://app.0sql.io ok

A wrong or missing key shows up on the first authenticated command instead:

$ zsql status
Unauthorized: an API key is required: Authorization: Bearer <key>

Next steps