Skip to content
Queria Docs
English
日本語English
Esc
↑↓navigate↵open⌘Jpreview
On this page

Authentication

How to issue an API token and register it with each tool

Queria’s public data can be read without authentication. Registering an API token raises the rate limits and lets you read your own private datasets. There are two ways to get a token:

  • queria login — obtain and save a token with browser approval alone (the primary method on a personal machine)
  • Manual issuance on the API tokens page at queria.io — for non-interactive environments such as CI and BI tools (manually issued tokens never expire)

The API tokens page is at queria.io/settings/tokens.

Either way, issuing a token requires a queria.io account, and account creation is currently invite-only.

Queria CLI

On a personal machine, run queria login. The approval page opens in your browser; press “Approve” and the token is saved automatically to ~/.config/queria/config.toml:

queria login    # obtain and save a token with browser approval
queria logout   # delete the saved token

The token expires in 90 days. Run queria login again to renew it. In environments where a browser cannot be opened, such as over SSH, use queria login --no-browser: approve the printed URL in a browser on any device, then paste the code shown on the page into the CLI.

Manually issued tokens are registered with queria auth:

queria auth set-token <token>   # saved to ~/.config/queria/config.toml (permissions 600)
queria auth status              # check whether a token exists and where it comes from
queria auth clear               # delete the saved token

Tokens are resolved in this order of precedence:

  1. The --token option
  2. The QUERIA_TOKEN environment variable
  3. The token key in the config file ~/.config/queria/config.toml (respects XDG_CONFIG_HOME)

A registered token is automatically attached as an Authorization header on requests to data.queria.io.

Python API

Pass token to queria.connect(). The Python API does not read environment variables or the config file automatically:

import queria

with queria.connect(token="YOUR_TOKEN") as conn:
    conn.sql("SELECT * FROM calendar.main.mart_calendar LIMIT 10").show()

MCP server

The MCP server uses the same token resolution as the CLI (the QUERIA_TOKEN environment variable → the config file). Save a token with queria auth set-token <token>, or pass the QUERIA_TOKEN environment variable in your MCP client’s configuration.

From plain DuckDB

Register the token as a DuckDB HTTP secret and every request made via ATTACH (catalog files and Parquet) carries the Authorization header. Run this before ATTACH:

CREATE SECRET queria_auth (
    TYPE http,
    BEARER_TOKEN 'YOUR_TOKEN',
    SCOPE 'https://data.queria.io'
);

Tokens that can change data

Reading data and changing it need different permissions. Creating a dataset, uploading to it, changing its visibility and deleting it, as well as creating, editing and deleting pages, all need a token with “Allow modifying datasets and pages” turned on. A token created without it is read-only.

The queria login approval page turns it on by default, so publishing from your own machine needs nothing extra. Manual issuance on the API tokens page is aimed at CI and BI tools and leaves it off, so turn it on when the token will change data.

A request made with a token that lacks the permission comes back as 403 naming what is missing: credentials:mint for queria push, datasets:write for queria create and queria delete, and pages:write for creating, editing and deleting pages.

A personal token reaches the datasets of every account you belong to, personal and organization. When you need a token that only updates one organization’s data, use the service tokens below.

Organization service tokens

These are tokens for updating data as an organization. They are created and revoked at queria.io/accounts/<handle>/settings/tokens, and only an admin of the organization can open that page.

  • The token acts as that account and reaches nothing else, including the personal account of whoever created it
  • queria create without --owner creates the dataset in that organization
  • The token keeps working when the person who created it leaves the organization. That is the point: a daily CI update should not depend on who is still on the team
  • The value is shown once. Leave the page and it can never be shown again

“Allow modifying datasets and pages” is on by default when you create one, since updating the organization’s data is what these tokens are for.

When a revoked token stops working

Revoking a token — with queria logout, or by deleting it on the API tokens page — takes up to 60 seconds to take effect. Until then, requests made with the revoked token may still succeed.

If you cannot wait out those 60 seconds, for example because a token may have leaked, delete the token and then assume requests can still succeed for the next 60 seconds. There is no way to cut a token off instantly.

Was this page helpful?