Skip to content

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.

Reference4 min read

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

Shell
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

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

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

On staging, use stage.bifrostorbit.com. How many requests each MCP server takes is in 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.

Was this page helpful?

Read next