vitna.ai/docs/routing/connected-accounts Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/routing/connected-accounts
> Raw Markdown: https://vitna.ai/docs/routing/connected-accounts.md
> Corpus index: https://vitna.ai/llms.txt

# Connected accounts

An org connects its OpenRouter account to Vitna from `/console`, by OAuth PKCE.
Vitna is never given a provider API key, and there is no field anywhere on this
site that would accept one.

```txt
/console  ->  Connect OpenRouter  ->  openrouter.ai/auth  ->  /auth/openrouter/callback
```

## What is granted, and what is not

What OpenRouter hands back is a key it minted for Vitna, scoped to the account
that approved it. An org's OpenAI, Anthropic and Google credentials are not part
of this and never travel: if they exist at all they sit in that org's own
OpenRouter workspace under BYOK, which is a relationship between that org and
OpenRouter that Vitna is not a party to.

The difference is worth stating precisely, because "connect your AI account"
usually means "paste your provider keys here".

| | Where it lives | Who can revoke it |
|---|---|---|
| An org's provider keys | The org's own OpenRouter workspace | The org, at OpenRouter |
| The key Vitna holds | Sealed in Vitna's database | The org, at OpenRouter |
| Anything typed into vitna.ai | Nothing is | n/a |

The third row is the point. Connecting is a redirect and a consent screen, so
there is no moment at which a credential is typed into this site, which means
there is no moment at which this site could leak one it was never given.

## Who may connect

An owner of the org. A membership admits somebody to read an org's register;
attaching a billable credential to that org is a different act, and it is the
first thing in the record to read the `owner` and `member` distinction that
`org_member` has carried since sign-in shipped. A member who presses the button
is refused with a sentence naming who can.

The check runs twice, at the start and again at the callback, because a
membership can be revoked while somebody is away at a consent screen and the act
that matters is the one that writes the row.

## The verifier is the whole security of the flow

OpenRouter's `/auth` takes a callback URL and a code challenge. It takes no
`state` parameter, so this flow cannot carry the correlation between the browser
that started a connection and the browser that came back the way the GitHub
sign-in carries it.

It carries it in the session instead. The PKCE verifier is generated on the
server, stored against the session that started the connection, and never sent
anywhere; OpenRouter receives only its sha256. Two consequences:

- A callback arriving in a browser that started nothing finds no pending row and
  is refused before any network call happens.
- A callback that does find one still cannot be completed with somebody else's
  authorization code, because the exchange presents this session's verifier
  against a challenge that code was never minted under.

The row is single use and lives ten minutes, which is OpenRouter's own lifetime
for an authorization code.

## What is refused

- A response that is not the shape of a key, however OpenRouter answered. A 200
  carrying an error is a refusal, not a key.
- A **management or provisioning key**. Those administer the account and mint
  other keys, a PKCE exchange should never produce one, and if the flow ever
  changes so that it can, Vitna declines rather than storing an
  account-administration credential it asked nobody for.
- A key that has already expired.
- An instance with no sealing key configured refuses before sending anybody to a
  consent screen, rather than after, so nobody grants a key that then has to be
  thrown away.

## How the key is held

Sealed with AES-256-GCM under a key in `/etc/vitna/env.site`, bound by additional
authenticated data to the provider, the org and the key's fingerprint, so a row
copied into another org's name fails to open rather than quietly billing the
wrong account.

Two properties are worth reading as claims somebody can check rather than as
reassurance:

- **The nightly dump carries ciphertext.** `vitna-backup.timer` copies this
  database to object storage, and the sealing key is not in it. This is the same
  reasoning `site.session` stores only a hash from.
- **The process that writes the key cannot read it back.** `vitna_auth` holds
  `INSERT` on `site.provider_connection` and a column-list `SELECT` that
  excludes `sealed_key`. Postgres refuses `SELECT sealed_key` for that role
  however it is spelled, by a future feature, a bug or an injection alike. It is
  the same shape of property `vitna_forms` has over the waitlist.

What sealing does **not** buy is worth saying too. A process holding the sealing
key that can read the column can open these values. So this is not a system in
which nobody can see the key. It is one in which the key is not in the database,
not in the backup, not on a screen, not in a log line, and not readable by the
process that wrote it.

## Disconnecting is two halves, and Vitna can only do one

**Forget this key** deletes the row. Vitna no longer holds the key and cannot
use it again.

It does not revoke the key at OpenRouter, and it cannot: a key minted by PKCE
belongs to the account that granted it. The console renders the owner's revoke
link beside the button rather than instead of it, and repeats it on the
confirmation, because a key Vitna has forgotten is still live until its owner
ends it.

Both links are built from the key's sha256, which is the digest OpenRouter's own
deep links are keyed on:

| | Where |
|---|---|
| What this key has done | `openrouter.ai/logs?api_key_hash=<sha256>` |
| Revoke it | `openrouter.ai/keys/<sha256>` |

They resolve only for the signed-in owner and 404 for anybody else.

## Nothing Vitna runs calls a provider with it

This is a control-plane connection and it does not put Vitna in the request
path. Nothing Vitna runs calls `/chat/completions` with it, usage arrives by
[`aperture:usage:import`](usage-import.md) from a file somebody exported or by a
runtime operator's own push, and no runtime a customer operates reads a
connection. Corrected 2026-09-13: this said nothing in this repository calls
`/chat/completions`. The customer-run runtime calls providers with the
operator's own keys, and the frozen [hosted router](router.md) would call
OpenRouter with a connected key; it is not installed on Vitna's box.

This section used to say what the connection was for: a next phase reading an
org's own usage from OpenRouter's analytics endpoints, so that the import stops
being an afternoon of exporting. A correction, dated 2026-08-26: that phase is
not possible under this grant, and
[issue #87](https://github.com/convexityos/vitna/issues/87) closed saying
so, with the findings and their sources in its comments. Every documented route
to day-granularity usage, `GET /api/v1/activity` and the Analytics API alike,
requires a management key; what an ordinary key may read is itself, and the key
Vitna holds serves no traffic by design, so its own counters would read zero,
permanently, about the wrong thing. The key a consent screen mints is an
ordinary key, and the refusal above to store anything more is not an obstacle
to remove: it is what makes the consent screen safe to approve, so the grant is
not widened to fit the feature.

The sealed key stands as this page describes it, held and unread, and the
console's sentence stays true as written. What would change the answer is
OpenRouter scoping a day-granularity read to the key class a consent screen can
mint.

## What the grant may serve, established rather than implied

The sentence above, that the key Vitna holds serves no traffic by design, says
what Vitna does with the key and was read twice as though it also said what the
key is able to do. Those are different claims and only the first was ever
checked. `docs/routing/router.md` names the gap: a credential class that cannot
serve inference is not a routing option at all, so the whole of that design's
C1 rung rests on an assumption nobody had sourced.

Established 2026-08-30, against OpenRouter's own documentation. A key minted by
the PKCE consent flow may call the inference endpoint. The
[OAuth PKCE page](https://openrouter.ai/docs/use-cases/oauth-pkce), retrieved
2026-08-30, carries a section headed "Step 3: Use the API key" whose sample
posts to `https://openrouter.ai/api/v1/chat/completions` with the exchanged key
as a bearer token, and tells the integrator to store it and use it to make
OpenRouter requests. The capability is the documented purpose of the flow
rather than a side effect of it.

**Issue #87 found the boundary in the other direction, and the two findings
agree.** OpenRouter separates the classes both ways: the
[management keys page](https://openrouter.ai/docs/features/provisioning-api-keys),
retrieved 2026-08-30, says management keys are exclusively for administrative
operations and cannot call the completion endpoints. So an ordinary key serves
traffic and cannot read the account, a management key reads the account and
cannot serve traffic, and the consent screen mints the first kind. #87 is not
evidence that this grant is narrow in general. It is the same partition seen
from the side that happened to be asked about first.

What this does not change is the section above it. Nothing Vitna runs calls
`/chat/completions` with a connection, and the console's sentence stays true of
what runs, because it describes a choice rather than a limit. What would change
it is operating the [hosted router](router.md), whose software exists, frozen
and not installed.

What it does not establish, and neither does anything else on this page:

- **Who is billed.** The key is minted under the granting account and
  [the limits page](https://openrouter.ai/docs/api-reference/limits), retrieved
  2026-08-30, describes spending as drawn from that account's balance under an
  optional per-key cap. Read as a documented mechanism, not as a settled
  commercial fact for a product that has no customers yet.
- **What it costs in rate limit.** The same page ties free-variant request
  limits to credits purchased on the account, which is the granting org's
  account and not Vitna's, so a shared ceiling is not the failure mode to
  design against. Nothing was measured.
- **That any of this should be built.** The capability question is settled and
  it was the smallest of the three preconditions on `docs/routing/router.md`.

## Configuring an instance

| Variable | What it is |
|---|---|
| `VITNA_CONNECTION_KEY` | 32 bytes of base64. Seals connected keys. |

```bash
openssl rand -base64 32
```

Without it, `/console` shows the connect affordance as unavailable and the start
route refuses. There is no OAuth client secret and nothing else to configure:
PKCE has no client credential, which is why there is nothing here to rotate if
it leaked.
Human Machine Shift+M