# Sign in with Orbit

> What OAuth sign-in Bifröst Orbit offers today: the OAuth 2 flow with PKCE that AI assistants use to connect to each satellite's MCP server, the Orbit app's own sign-in, and what doesn't exist yet.

Source: https://docs.bifrostorbit.com/orbit/developers/sign-in-with-orbit/

People sign in to Bifröst Orbit once, at Orbit, with an email code, Microsoft or Google. Two kinds of app can use that sign-in today:

- **AI assistants and other MCP clients**, such as Claude, ChatGPT, Cursor or VS Code. They connect to a satellite's MCP server with OAuth 2 and PKCE, as the person who signs in.
- **The Orbit app** for iPhone, through Orbit's own sign-in for it.

Websites and apps of your own can't use Orbit to sign their users in yet. There is no OpenID Connect: no ID token, no user info endpoint and no `openid`, `profile` or `email` scopes. Orbit has no way to register an app for that, and the Orbit app's sign-in only accepts the Orbit app.

## Connect an MCP client

Every satellite runs its own OAuth server for its MCP server, at the satellite's path. Any client can register itself, with no key, so an assistant only needs the MCP address, such as `https://app.bifrostorbit.com/commerce/mcp`. Most assistants do every step below on their own: you add the address, and the person signs in when asked.

### 1. Find the OAuth server

A request to the MCP server without a token answers `401`, with the address of its description in `WWW-Authenticate`:

```http
WWW-Authenticate: Bearer realm="cms-orbit", resource_metadata="https://app.bifrostorbit.com/cms/.well-known/oauth-protected-resource/mcp"
```

That description names the OAuth server, `https://app.bifrostorbit.com/cms`, whose metadata is at `/cms/.well-known/oauth-authorization-server`. The same metadata is also at `/.well-known/oauth-authorization-server/cms` on the host, for clients that look there.

### 2. Register the client

```bash
curl -X POST https://app.bifrostorbit.com/commerce/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"Northwilds stock assistant","redirect_uris":["http://localhost:8765/callback"]}'
```

It answers `201` with a `client_id`. Give one to ten redirect addresses: `https` addresses, or `http` on `localhost`, `127.0.0.1` or `[::1]`, without a `#` part. Only public clients are supported: leave out `token_endpoint_auth_method`, or set it to `none`. There is no client secret.

### 3. Send the person to sign in

Make a random code verifier, and open the authorise address with its SHA-256 challenge:

```text
https://app.bifrostorbit.com/commerce/oauth/authorize
  ?response_type=code
  &client_id=com_client_…
  &redirect_uri=http://localhost:8765/callback
  &code_challenge=<base64url of the SHA-256 of the verifier>
  &code_challenge_method=S256
  &state=<a random value>
```

The person signs in at Orbit if they haven't yet, then chooses what the assistant may reach and selects **Allow**. The choice depends on the satellite: a website in CMS Orbit, a shop in Commerce Orbit, a brand in Travel Orbit, and an organisation in the others. The browser then goes back to your redirect address with `code` and `state`, or with `error=access_denied` if they cancel. The code works once, for 60 seconds.

### 4. Get a token

```bash
curl -X POST https://app.bifrostorbit.com/commerce/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=com_client_… \
  -d code=… \
  -d code_verifier=… \
  -d redirect_uri=http://localhost:8765/callback
```

```json
{ "access_token": "com_mcp_…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "com_mrt_…", "scope": "commerce" }
```

Send the access token to the MCP server as `Authorization: Bearer com_mcp_…`. It lasts an hour. Ask for a new one with `grant_type=refresh_token`, `refresh_token` and `client_id`: each refresh gives a new pair, and a refresh token lasts 30 days.

### What a token can do

A token works only on the MCP server of the satellite that issued it, never on the satellite's other APIs or on another satellite. It acts as the person who signed in, with their role in that satellite, and stops working when they lose access. Each satellite lists connected assistants under **AI assistants**, or **AI agents** in CMS Orbit, where people disconnect their own and admins can disconnect any.

| Satellite | OAuth server | Scope | The person chooses | Revoke address |
| --- | --- | --- | --- | --- |
| CMS Orbit | `https://app.bifrostorbit.com/cms` | `cms:draft` | A website. AI agents must be switched on for it | None. Disconnect it in CMS Orbit |
| Careers Orbit | `https://app.bifrostorbit.com/careers` | `careers` | An organisation | `/careers/oauth/revoke` |
| Commerce Orbit | `https://app.bifrostorbit.com/commerce` | `commerce` | A shop | `/commerce/oauth/revoke` |
| Travel Orbit | `https://app.bifrostorbit.com/travel` | `travel` | A brand | `/travel/oauth/revoke` |
| Booking Orbit | `https://app.bifrostorbit.com/booking` | `booking` | An organisation | `/booking/oauth/revoke` |
| Presence Orbit | `https://app.bifrostorbit.com/presence` | `presence` | An organisation | `/presence/oauth/revoke` |
| Insights Orbit | `https://app.bifrostorbit.com/insights` | `insights:read` | An organisation, on a plan with AI assistants | None. Disconnect it in Insights Orbit |

On staging, use `stage.bifrostorbit.com`. How many requests each MCP server takes is in [Rate limits](https://docs.bifrostorbit.com/orbit/developers/rate-limits/).

### Errors

The token endpoint answers OAuth errors as `{ "error": "invalid_grant", "error_description": "…" }`: `invalid_request` for a missing field, `invalid_grant` for a used or expired code, a verifier that doesn't match or a person who no longer has access, and `unsupported_grant_type` for any grant other than `authorization_code` and `refresh_token`. A redirect address the client didn't register is refused on the sign-in page, without going back to it.

## The Orbit app

The Orbit app signs in with OAuth 2 and PKCE too, at `app.bifrostorbit.com/api/mobile/oauth/authorize`, and calls Orbit's mobile API. That sign-in accepts only the Orbit app: other apps can't register for it, and its tokens only work in the mobile API.
