Skip to content
extraorbital
Documentation ExtraOrbital
Browse documentation

Start here

Keyless on platforms without OIDC

Let code on Val Town ask ExtraOrbital for the resources it needs, with the token its platform already gives it. Nothing to set up, nothing to copy.

How it works

  1. The code sends its platform token. On Val Town that is the valtown variable every val is given, plus the val's id.
  2. The platform vouches for it. ExtraOrbital asks Val Town's API which account the token belongs to, and checks that the val belongs to that account.
  3. ExtraOrbital finds where it belongs. That is the ExtraOrbital account with the same email address (created if there is none), its default team, and a project made for this val. The same val always gets the same project.
  4. The code receives the credentials. Resources it names that do not exist yet are created first.

Every step is cached, so after the first call the answer comes back without asking the platform again.

On Val Town

ts
import { getServerCredentials } from "https://esm.town/v/extraorbital/sdk/main.ts";

const { env } = await getServerCredentials(["mongo/app", "redis", "s3/uploads"]);
// env.MONGODB_URI, env.REDIS_URL, env.S3_BUCKET …

Or call the API directly:

ts
import { getValId } from "https://esm.town/v/std/utils/index.ts";

const response = await fetch("https://extraorbital.dev/api/v1/exchange/valtown", {
  method: "POST",
  headers: { authorization: `Bearer ${Deno.env.get("valtown")}`, "content-type": "application/json" },
  body: JSON.stringify({ project: await getValId(), resources: ["mongo/app", "redis"] }),
});
const { credentials, env, skipped } = await response.json();

A resource is service/slug. The slug defaults to default, so redis means redis/default. You can ask for up to 20 at a time.

Which account, team and project

  • Account. The ExtraOrbital account with the platform account's email address. If there is none, one is created, and signing in with that address later opens it. If the platform does not verify addresses, an account that already exists is never reached this way (403 EXCHANGE_EMAIL_UNVERIFIED). Val Town verifies them.
  • Team. That account's default team, on its plan. The free allowance and its limits apply as usual: a resource it does not cover is listed in skipped with PAYMENT_REQUIRED and a link to add a card.
  • Project. vt- followed by 16 characters derived from the platform account and the val, labelled username/val. Another val gets another project.

What the code receives

The service can…The code gets
expire a credential itselfits own credential, which stops working within the hour, as with keyless access
mint a credential per holder, but not expire ita credential of its own, revoked when you remove the app's access
only share one credentialthe resource's shared credential, as you would read it yourself

Manage access

The app is listed with your keyless apps, in the project's Env vars tab and with extraorbital remote.

  • Narrow it to some resources. It can no longer read the others, and it cannot create new ones.
  • Remove it. What it holds is revoked at once, and the app is refused from then on. To let it in again, delete its project.

API

Route
POST /exchange/:providerAuthorization: Bearer <platform token>, body { project, resources: ["mongo/app", { resource: "redis", slug: "cache" }] } → { projectId, teamId, credentials: { "mongo/app": { env, expiresAt, shared } }, env, expiresAt, skipped, authorization }

expiresAt is null for a credential that does not expire on its own. Errors are 401 UNAUTHORIZED (the platform refused the token, or the project is not the account's), 403 OIDC_NOT_AUTHORIZED (you removed the app's access), 403 EXCHANGE_EMAIL_UNVERIFIED and 429 RATE_LIMITED (300 calls a minute per platform account). A resource that cannot be handed out is listed in skipped with its code, rather than failing the call.