# Connect an app with OAuth (/build/connect-an-app)

Register an app or a web page, get the owner's approval by the code flow or the device flow, and keep its access token fresh.



An app connects with **OAuth**: the owner approves it once in their browser, and the app receives an access token that begins `marfa_at_`. It goes in the same `Authorization` header as a key and reaches only what the owner approved. **No app ever needs the owner's password.** A script uses a [key](/use/manage-keys) instead, sent as [a request shows](/reference/api#send-a-request).

The instance is its own authorization server. Its discovery document at `/.well-known/oauth-authorization-server` names the endpoints under `/oauth/`, and **every client is public**: it holds no secret and proves itself with PKCE. In Swift, `Authorization` takes every step ([the Swift SDK](/reference/swift-sdk#sign-in)), and an MCP client follows them itself.

## Register the app [#register-the-app]

Registration needs no credential. A scope is a type and a level, such as `core.file.image:read`, a [permission](/build/access#what-a-credential-reaches), or `offline_access` for a refresh token. The grants say which flows the app uses:



**Code flow**

```http
POST /oauth/register
Content-Type: application/json

{
  "client_name": "Photo frame",
  "application_type": "native",
  "redirect_uris": ["com.example.frame:/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scope": "core.file.image:read offline_access"
}
```

**Device flow**

```http
POST /oauth/register
Content-Type: application/json

{
  "client_name": "Photo frame",
  "application_type": "native",
  "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"],
  "scope": "core.file.image:read offline_access"
}
```

Marfa answers `201` with the `client_id`; an app can instead name itself by the `https` address of a client ID metadata document ([Register an OAuth client](/reference/api/apps/registerOAuthClient)). **`offline_access` needs the `refresh_token` grant:** without it Marfa refuses the registration, or a device request for the scope with `400 invalid_scope`. **Name the scopes the app needs:** a registration with none gets the [default scopes](/catalog/permissions), read and write on all content and its edges. Content leaves out `app` types: **an app that signs in again, or on another computer, asks for `app.<vendor>.*:write`** to reach [its own items](/build/access#an-apps-own-types).

The redirect address decides the kind. A **web** client, the default, takes `https` addresses with a real host name. A **native** client may also use `http://127.0.0.1` with any port, or a reverse domain name you control as a scheme.

## Send the owner to approve [#send-the-owner-to-approve]

Make a fresh verifier and `state` for every attempt, and keep both until the exchange. Marfa takes only the `S256` challenge. This runs in a browser and in Node 22 or later, with `instance` set to your instance's address:

```ts title="authorize.ts"
const base64url = (bytes: Uint8Array) =>
  btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
const random = () => base64url(crypto.getRandomValues(new Uint8Array(32)));

const verifier = random();
const state = random();
const challenge = base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
const authorizeUrl = `${instance}/oauth/authorize?` + new URLSearchParams({
  response_type: "code", client_id: clientId, redirect_uri: redirectUri, scope: "core.file.image:read offline_access",
  code_challenge: challenge, code_challenge_method: "S256", state,
});
```

Open `authorizeUrl` in the owner's browser. The owner approves the app, as [Connect your agent](/connect-your-agent#approve-what-it-may-reach) shows. A write or a permission the app doesn't already hold needs a sign-in from the last fifteen minutes, so the page may ask the owner to confirm it's them. Marfa sends the browser to your redirect address with `code`, `state` and `iss`; a denial carries `error=access_denied` and no code. **Before you exchange the code, check there is no `error`, that `state` is the one you sent, and that `iss` is the `issuer` of the discovery document.**

## Exchange the code for tokens [#exchange-the-code-for-tokens]

Post the code and verifier to `/oauth/token` as a form:

```http title="Request"
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=com.example.frame%3A%2Fcallback&client_id=<client_id>&code_verifier=<verifier>
```

Marfa answers `200` with an `access_token` that lasts `expires_in` seconds (3600), a `refresh_token` if the app asked for `offline_access`, and `scope`, which **can be less than you asked for**. A code works once: sending it again answers `400 invalid_grant` and, while the code is unexpired, ends the tokens it gave.

Before the access token expires, post `grant_type=refresh_token`, the `refresh_token` and the `client_id` to the same endpoint. **Each exchange ends the refresh token you sent**, and a used one answers `400 invalid_grant` and ends every token in its chain, with no grace. So every caller of one token shares one refresh, and saves the new refresh token at once. Processes that share a stored token also take a lock around reading, refreshing and saving it. After an answer that isn't a clear `200`, such as a timeout or a `5xx`, the token may be spent: **start the approval again**, since a retry would end the chain.

```ts title="refresh.ts"
let inFlight: Promise<string> | undefined;

export function accessToken(): Promise<string> {
  if (Date.now() < tokens.expires_at - 60_000) return Promise.resolve(tokens.access_token);
  return (inFlight ??= refresh().finally(() => (inFlight = undefined)));
}

async function refresh(): Promise<string> {
  const response = await fetch(`${instance}/oauth/token`, {
    method: "POST",
    body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: tokens.refresh_token, client_id: clientId }),
  }).catch(() => undefined);
  if (response?.status !== 200) throw new Error("The refresh wasn't confirmed: start the approval again");
  const next = await response.json();
  tokens = { access_token: next.access_token, refresh_token: next.refresh_token, expires_at: Date.now() + next.expires_in * 1000 };
  await saveTokens(tokens);
  return tokens.access_token;
}
```

To disconnect, post the refresh token as `token`, with the `client_id`, to `POST /oauth/revoke` as a form: it ends the app's tokens and the owner's approval. The owner can also cut an app off ([See and revoke access](/use/see-and-revoke-access)).

## Connect with the device flow [#connect-with-the-device-flow]

A tool or device with no browser shows the owner a short code to approve elsewhere, as `marfa login` does. Register as the Device flow tab shows, with no redirect address. Then ask for a code, naming the scopes, since a request with none answers `400 invalid_scope`:

```http title="Request"
POST /oauth/device-authorization
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&scope=core.file.image%3Aread%20offline_access
```

Marfa answers `user_code`, `verification_uri` and `device_code`. Show the owner the first two, then post `grant_type=urn:ietf:params:oauth:grant-type:device_code` with the `device_code` and `client_id` to `/oauth/token`, **waiting `interval` seconds between requests and stopping after `expires_in` seconds**. Until the owner decides, Marfa answers `400 authorization_pending`: keep polling. `400 slow_down` means you polled too soon: add five seconds to `interval` **for this and every later poll**. **`access_denied`, `expired_token` and `invalid_grant` end the polling**: the owner refused, the code ran out, or the code was used already. Approval gives the same tokens as the code exchange.

## Connect a web page [#connect-a-web-page]

A web page takes the same steps in its own script, registered as a web client, with no key. It needs an `https` address with a real host name, so a page on `http://localhost` can't connect, and a callback page at its redirect address. Open the approval in a small window from a click, listen first for the callback, and keep only the answer that carries your `state`. The callback page runs at the page's own origin, so it passes the result over the channel and closes:



**Page**

```ts
const discovery = await (await fetch(`${instance}/.well-known/oauth-authorization-server`)).json();
const answered = new Promise<URLSearchParams>((resolve) => {
  const channel = new BroadcastChannel("marfa-approval");
  channel.onmessage = (event) => {
    const answer = new URLSearchParams(event.data);
    if (answer.get("state") !== state) return; // not an answer to this request
    channel.close();
    resolve(answer);
  };
});
open(authorizeUrl, "marfa-approval", "popup,width=480,height=640");

const answer = await answered;
if (answer.get("error") || answer.get("iss") !== discovery.issuer) throw new Error("Not approved, or not from the instance");
const response = await fetch(discovery.token_endpoint, {
  method: "POST",
  body: new URLSearchParams({
    grant_type: "authorization_code", code: answer.get("code")!, redirect_uri: redirectUri, client_id: clientId, code_verifier: verifier,
  }),
});
const tokens = await response.json();
```

**Callback page**

```html
<script>
  new BroadcastChannel("marfa-approval").postMessage(location.search);
  close();
</script>
```

**Don't send `credentials: "include"`:** Marfa allows no credentials on a cross-origin answer, so the access token is the page's only authority. Let the page cancel the wait: an owner who closes the window sends nothing. For a browser that blocks windows, redirect the whole page instead and keep the verifier and `state` in `sessionStorage`. Keep the tokens in the page's memory, or in `sessionStorage` if a reload must keep the owner signed in, and never in a URL. Refresh them as above.

Approving the page lets the origin of each redirect address it registered call the instance from a browser until the last app approved there is disconnected; an owner can name an origin earlier with the `cors_origins` [setting](/run/settings). A registration nobody approves is removed after an hour idle.

The rules are in the [keys and sign-in](https://github.com/withmarfa/marfa/blob/main/conformance/spec/keys-and-oauth.md#web-pages) chapter of the contract.
