---
title: Authentication
description: How to issue an API token and register it with each tool
---

Queria's public data can be read without a token. Registering an API token raises the [rate limits](/en/limits) and lets you read your own private datasets. There are three ways to get a token.

- `queria login`: approve in the browser, and a token is issued and saved in the CLI. Use this on your own computer
- Issue one on the API tokens page at queria.io: for places where you can't approve in a browser, such as CI and BI tools. You choose the expiration when you issue the token: 30 days, 90 days, 1 year, or no expiration (the default is 1 year)
- Add the MCP server (`https://mcp.queria.io`) to an AI chat: when you approve it in Claude or another AI chat, that AI chat gets a token. It renews itself while in use and stops working after 90 days without use. See [MCP server](/en/mcp)

The API tokens page is at [queria.io/settings/tokens](https://queria.io/settings/tokens).

Either way, issuing a token requires a queria.io account, which is [free to create](/en/account).

## 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`:

```bash
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`:

```bash
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:

```python
import queria

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

## MCP server

The MCP server (`https://mcp.queria.io`) receives its token through the sign-in and approval screen that opens when you add it to a client. For a client that cannot open that screen, issue a token on the API tokens page and pass it as `Authorization: Bearer <API token>`. See [MCP server](/en/mcp#sign-in-and-consent).

## 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:

```sql
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, creating, editing and deleting reports, changing stars and follows, and deleting comments all need a token with "Allow modifying datasets and reports" 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: `datasets:write` for `fdl push`, `queria create` and `queria delete`, `reports:write` for creating, editing and deleting reports, `stars:write` for `queria star add` and `queria star remove`, `follows:write` for `queria follow add` and `queria follow remove`, and `comments:write` for `queria comment delete`.

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.

## Tokens that manage organizations

To change an organization's members, invitations, teams, tokens, GitHub Actions registrations, or profile through the API or `queria org`, you need a token with the `accounts:admin` permission. Tokens from `queria login` or the API tokens page do not have it.

Run `queria auth refresh --scopes accounts:admin` and the approval page asks you to approve organization admin access. After you approve, a token with only `accounts:admin` is issued.

- The token expires in 1 hour. Run the same command again to get a new one
- It cannot change datasets or reports
- It appears as "Organization admin" under "Connected apps and devices" on the API tokens page, where you can revoke it
- Organization service tokens cannot have it. They also cannot list organizations or their members

Sending a change with a token that lacks the permission returns 403 with `insufficient_scope`. Listing organizations and members works with your usual personal token.

## 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
- Stars, follows and comments belong to a person, so this token cannot change them
- 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 reports" is on by default when you create one, since updating the organization's data is what these tokens are for.

## Updating from GitHub Actions [#github-actions]

A GitHub Actions job can update an organization's data without a token stored in the repository. The job sends GitHub's OIDC token to Queria, which checks it against the registrations and returns a token valid for 1 hour.

Register repositories under "GitHub Actions" at `queria.io/accounts/<handle>/settings/tokens`. Press "Add registration" to open the form. Only organization admins can open this page.

Each registration is a combination of the three fields below. A job receives a token only when it matches all three fields of one registration. To allow jobs with different conditions, add more registrations.

| Field | Description |
| --- | --- |
| Repository | `owner/repository` (for example `queria-io/dataset-mext`). Enter only the owner to allow every repository of the owner. Private repositories can be registered |
| Workflow | The file name of the workflow that runs the job (for example `sync.yml`). To call a reusable workflow in another repository, enter the called workflow's path as `owner/repository/.github/workflows/file.yml`. When "Repository" holds only the owner, also enter the workflow as a path; only jobs that run the workflow at that path receive a token. When the caller references the called workflow by a tag or another branch, append the ref to the path, for example `@refs/tags/v1`. Without a ref, the workflow is matched on the branch entered in "Branch". When the caller pins the called workflow to a commit SHA, only the workflow path is compared |
| Branch | The branch the job runs on (for example `main`) |

- The owner is stored as GitHub's numeric ID when you register it. A renamed owner, or a new one created under the same name, cannot use the registration. The repository is matched by its name within that owner, ignoring case. After renaming a repository, register it again under the new name
- An owner can be registered by only one account. You cannot register an owner that another account has already registered
- Only jobs run by `push`, `schedule` or `workflow_dispatch` receive a token. Jobs run from pull requests do not
- The token is issued on behalf of the admin who registered the repository and has the same permissions as an organization service token. If that admin leaves the organization, the registration stops working

Give the job the `id-token: write` permission. The queria CLI makes this exchange on its own in a job with no token set, and reuses the token for its hour.

```yaml
permissions:
  contents: read
  id-token: write
steps:
  - run: pip install queria
  - run: queria report edit my-org/report report.md
```

Without the CLI, send an OIDC token with the audience `https://queria.io` to `https://queria.io/api/oidc/github/token`.

```yaml
permissions:
  contents: read
  id-token: write
steps:
  - name: Get a Queria token
    run: |
      oidc=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
        "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://queria.io" | jq -r .value)
      token=$(curl -sS -X POST https://queria.io/api/oidc/github/token \
        -H "Content-Type: application/json" -d "{\"token\":\"$oidc\"}" | jq -r .token)
      echo "::add-mask::$token"
      echo "QUERIA_TOKEN=$token" >> "$GITHUB_ENV"
```

The token expires after 1 hour. For a job that runs longer, get a new one the same way before it expires (the CLI gets a new one when less than 10 minutes remain).

## 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.
