Skip to content
extraorbital
Documentation ExtraOrbital
Browse documentation

Start here

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.

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:

PlatformFound fromProven with
Vercel.vercel/project.json (vercel link)Your Vercel login (vercel login or VERCEL_TOKEN), at once
GitHub Actionsa github.com git remoteOne run of a CI job, within 7 days
GitLab CIa gitlab.com git remoteOne 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.

PlatformWhy not
NetlifyFunctions get no identity token
RailwayServices get no identity token
Cloudflare WorkersWorkers get no identity token
RenderIts 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.

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.

API

Route
GET POST /projects/:projectId/oidc/authorizationsList, or create one pending: { platform, expect, environments?, resources?, replace? } → { authorization, proof: { code, audience, expiresAt, verifyUrl } }
PATCH DELETE /projects/:projectId/oidc/authorizations/:idChange 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/:slugOne resource's variables for Authorization: Bearer <identity token>; x-extraorbital-project pins the project
GET /oidc/envEvery 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).