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
- The code sends its platform token. On Val Town that is the
valtownvariable every val is given, plus the val's id. - 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.
- 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.
- 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
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:
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
skippedwithPAYMENT_REQUIREDand a link to add a card. - Project.
vt-followed by 16 characters derived from the platform account and the val, labelledusername/val. Another val gets another project.
What the code receives
| The service can… | The code gets |
|---|---|
| expire a credential itself | its own credential, which stops working within the hour, as with keyless access |
| mint a credential per holder, but not expire it | a credential of its own, revoked when you remove the app's access |
| only share one credential | the 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/:provider | Authorization: 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.