# 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.

<Callout title="In brief">

- Some platforms give running code no identity token, only a token for their own API. ExtraOrbital asks that API who the code belongs to.
- The code names the resources it wants, such as `mongo/app` or `redis`. Whatever is missing is created, in a project made for that app, in the default team of the ExtraOrbital account with the platform account's email address.
- Works with Val Town today. Val Town is winding down: code goes read-only on December 10, 2026, and vals stop on January 10, 2027.

</Callout>

## 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 itself | its own credential, which stops working within the hour, as with [keyless access](/docs/keyless) |
| 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.

---

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