Connect with Aurochs

How it works

1. 1Register your app at Connect → Your integrations to get a client_id.
2. 2Send the user to /api/auth/oauth2/authorize. They pick which workspace to connect and approve the scopes you ask for.
3. 3Exchange the returned code at /api/auth/oauth2/token for an access token.
4. 4Call /api/v1/pages, /api/v1/databases, … directly. Your token already knows its workspace — there is none in the URL.

Endpoints

Everything is discoverable — most OAuth libraries can configure themselves from this one URL:

Scopes

Ask for read write offline_access unless you only need to read. There is also an adminscope for workspace management, but it isn’t available to third-party apps.

What a token can actually do

Example

Standard authorization code + PKCE. Send the user here:

GET https://aurochs.oxen.dev/api/auth/oauth2/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read%20write%20offline_access
  &state=RANDOM
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

Then exchange the code:

curl -X POST https://aurochs.oxen.dev/api/auth/oauth2/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://yourapp.com/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d code_verifier=THE_VERIFIER
# → { "access_token": "...", "refresh_token": "...", "expires_in": 900 }

And call the API:

# Which workspace am I connected to?
curl https://aurochs.oxen.dev/api/v1/workspace -H "Authorization: Bearer ACCESS_TOKEN"

# No workspace in the URL — the token carries it.
curl https://aurochs.oxen.dev/api/v1/pages     -H "Authorization: Bearer ACCESS_TOKEN"

Things worth knowing

• PKCE is required (S256 only), for every app — not just public ones.
• No client secret if your code ships to users — browser apps, native apps and extensions register as public clients and use PKCE alone. A secret in shipped code isn’t a secret.
• Refresh tokens rotate. Each refresh returns a new one and invalidates the old. Store the newest and never retry with a spent token — reusing one is treated as theft and revokes the whole chain.
• There’s no ID token.We don’t implement OIDC. Use /api/v1/me for identity.
• One workspace, chosen by the user. If they want you in a second one, they connect you again and pick it. There is no way to ask for more than they granted, and reconnecting replaces the choice rather than adding to it.
• Access tokens last 15 minutes— so a user’s “Disconnect” takes effect quickly. Use the refresh token.
• Redirect URIs match exactly — including path and query. Register every one you use.
• Building an assistant instead? Point any MCP client at https://aurochs.oxen.dev/api/mcp — same OAuth server, no registration. Assistants act as the person across alltheir workspaces, so they aren’t workspace-bound and don’t use this REST API. If you’re building a tool rather than an agent, you want the flow on this page.

The button

Use this to start the flow, so the moment looks the same everywhere people meet it.

Copy the markup:

<a href="https://aurochs.oxen.dev/api/auth/oauth2/authorize?client_id=…" style="display:inline-flex;align-items:center;gap:10px;padding:10px 16px;border-radius:9px;background:#1c201c;color:#f3efe6;font:500 14px system-ui;text-decoration:none">
  <img src="https://aurochs.oxen.dev/brand/aurochs-icon-svg-white.svg" width="18" height="18" alt="">
  Connect with Aurochs
</a>

Don’t alter the mark or the wording. Say “Connect with Aurochs” — not “Log in with”, since it grants access to content rather than creating an account. The full brand kit — both colourways, the palette, and every asset — is at /brand.json.

Reference