# Keyless access

> Let an app on Vercel, GitHub Actions, GitLab CI or Google Cloud read your project's variables with its platform's identity, without storing them.

<Callout title="In brief">

- Run `npx extraorbital push vercel --keyless` (or `github`, `gitlab`, `gcp`) in your app's folder. It finds the app, asks what it may read, and proves the app is yours.
- In the app, read the variables at runtime with `fromOIDC()` from any `@extraorbital` package. Nothing is copied into the platform.
- Every value the app receives stops working after an hour. The app asks again when it needs to.
- Works with Vercel, GitHub Actions, GitLab CI and Google Cloud.

</Callout>

## How it works

1. **You authorize an app.** For example: *Vercel project web may read DATABASE_URL and REDIS_URL from project shop.*
2. **Its platform vouches for it.** When the app runs, Vercel (or GitHub, GitLab, Google) gives it a short signed note saying who it is. Nobody else can sign it.
3. **ExtraOrbital checks, then answers.** The note is checked against your authorization, and the app receives the variables, as credentials that expire within the hour.

The app never holds a long-lived secret, and there is nothing to rotate on the platform.

## Set it up

```sh
npx extraorbital push vercel --keyless
npx extraorbital push github --keyless
npx extraorbital push gitlab --keyless
npx extraorbital push gcp --keyless --service-account web@acme.iam.gserviceaccount.com
npx extraorbital push --keyless          # whatever the folder belongs to, asked if there are several
```

Run it in the app's folder, signed in to ExtraOrbital and linked to the project (`extraorbital link`). It reads what the platforms' own tools left there:

| Platform | Found from | Proven with |
| --- | --- | --- |
| Vercel | `.vercel/project.json` (`vercel link`) | Your Vercel login (`vercel login` or `VERCEL_TOKEN`), at once |
| GitHub Actions | a `github.com` git remote | One run of a CI job, within 7 days |
| GitLab CI | a `gitlab.com` git remote | One run of a CI job, within 7 days |
| Google Cloud | `--service-account <email>` | `gcloud`, at once |

### Why the app is proven first

Anyone can type a Vercel project id or a repository name. If typing it were enough, someone could authorize *your* app in *their* project, and your app would quietly read their database. So an authorization only becomes active once the app itself proves who it is: a token from the app, addressed to a one-time code the CLI received. What gets authorized is read from that token's permanent ids (never names, which can be renamed or re-registered), not from what was typed.

- **Vercel**: the CLI asks Vercel, with your login, for a development token for the project and addresses it to the code. Only someone who can act on the project gets one. OIDC Federation must be on in the project's settings (Security), which it is for new projects.
- **GitHub Actions**: the CLI prints a job to add. It runs once, from that repository only:

```yaml
permissions:
  id-token: write
jobs:
  extraorbital-proof:
    runs-on: ubuntu-latest
    steps:
      - run: npx extraorbital remote verify <code>
```

- **GitLab CI**: the same, with the proof token named in `id_tokens` (the CLI prints the exact job).
- **Google Cloud**: `gcloud auth print-identity-token --impersonate-service-account`, which needs the *Service Account OpenID Connect Identity Token Creator* role on the service account.

## Use it in the app

```ts
import { fromOIDC } from "@extraorbital/neon/oidc"

const db = await fromOIDC()                     // the "default" Neon database
const cache = await (await import("@extraorbital/redis/oidc")).fromOIDC({ slug: "cache" })
```

Each package's `fromOIDC()` builds the same value its main import does. It asks the platform for an identity token, exchanges it, and keeps the answer until five minutes before it expires; on Next.js it is also kept in the data cache. On Vercel, installing `@vercel/oidc` lets a local development token refresh itself.

In CI, run a command with every variable the job may read, with no ExtraOrbital login:

```sh
npx extraorbital run --oidc -- npm test
```

GitHub needs `permissions: id-token: write`. GitLab needs an `EXTRAORBITAL_ID_TOKEN` in the job's `id_tokens`, with `aud: https://extraorbital.dev`.

### Pin the project

An app is authorized for one project at a time, so its token alone says which project to read. To make sure it is the one you expect, set `EXTRAORBITAL_PROJECT_ID` in the app: a token authorized for another project is then refused.

## Manage access

```sh
npx extraorbital remote                    # every app with keyless access, and every pushed destination
npx extraorbital remote remove acme/web    # take an app's access away
npx extraorbital rotate remote acme/web    # revoke what it holds now; it fetches new credentials
```

The project's **Env vars** tab lists every variable, which apps can read it, and the apps with keyless access. **Remove access** stops an app at once: the values it already holds stop working.

Each environment of an app (Vercel's production, preview and development; a GitHub environment) belongs to one project. Authorizing it again for another project is refused; `--replace` takes it over, once proven, and the project it leaves records it.

## What can be read this way

A resource can be read keylessly when its provider hands out a separate credential per app that expires on its own: Neon, MongoDB, Redis on paid plans, S3, R2, B2, OpenRouter, Deepgram, Gladia, Realtime, Sandbox, and Authlocker with its partner API. The shared credential is never handed out. Supabase, Upstash Vector, Git, Stripe test keys and MongoDB databases made on the legacy provider answer `409 OIDC_UNSUPPORTED`: keep them in the platform's variables (`extraorbital push vercel`, or `push ./file.env` for any other host).

## Platforms that cannot use it

Keyless access needs the platform to give your code a signed identity token that it can address to ExtraOrbital.

| Platform | Why not |
| --- | --- |
| Netlify | Functions get no identity token |
| Railway | Services get no identity token |
| Cloudflare Workers | Workers get no identity token |
| Render | Its tokens can only be addressed to AWS, Google Cloud, Anthropic or OpenAI |

On those, write the variables to a file only you can read with `npx extraorbital push ./prod.env`, and copy them into the platform's settings. See [Deploy and rotate](/docs/deploy-and-rotate).

Some platforms give your code a token for their own API instead, and ExtraOrbital can ask that API who the code belongs to. Val Town works this way: see [Keyless on platforms without OIDC](/docs/token-exchange).

## API

| Route | |
| --- | --- |
| `GET POST /projects/:projectId/oidc/authorizations` | List, or create one pending: `{ platform, expect, environments?, resources?, replace? }` → `{ authorization, proof: { code, audience, expiresAt, verifyUrl } }` |
| `PATCH DELETE /projects/:projectId/oidc/authorizations/:id` | Change its environments or resources, or remove it. What is taken off is revoked at once |
| `POST /oidc/authorizations/verify` | `{ code }` with `Authorization: Bearer <token addressed to <audience>/proof/<code>>`. No login |
| `GET /oidc/:service/:slug` | One resource's variables for `Authorization: Bearer <identity token>`; `x-extraorbital-project` pins the project |
| `GET /oidc/env` | Every variable the app's authorization covers, merged; resources that cannot be read keylessly are listed in `skipped` |

Every identity token must be addressed to `https://extraorbital.dev`. Errors: `401 UNAUTHORIZED` (token refused), `403 OIDC_NOT_AUTHORIZED` (no authorization for this app and environment, or another project pinned), `409 OIDC_TAKEN` (the app is authorized for another project), `409 OIDC_UNSUPPORTED` (the resource cannot expire a credential).

---

More for agents: [Sitemap](https://extraorbital.dev/sitemap.md) · [llms.txt](https://extraorbital.dev/llms.txt) · [agents.md](https://extraorbital.dev/agents.md)
