Skip to main content
This page is intentionally non-technical so you can align product, engineering, and design on how Mio behaves before you dive into the Quickstart.

​
How the integration flows

  1. Invite the user – your interface launches the OAuth consent screen hosted by Mio. Users review what Mio will read (email + calendar) before approving.
  2. Confirm the connection – Mio redirects back to your redirect URL with a short-lived authorization code. The browser keeps minimal state.
  3. Exchange and store – your backend trades the code for durable tokens, encrypts the refresh token, and associates everything with the current account.
  4. Get Mio Context – whenever you need personalized output, your backend or front-end asks Mio for context and passes it into your own prompts, emails, or experience.
  5. Refresh in the background – the backend renews tokens on a schedule so users stay connected without repeating OAuth.
Align on ownership early: the browser handles UX, the backend safeguards secrets, and Mio’s context layer returns ready-to-use insights about each user.

​
OAuth & token lifecycle

  1. Start the connection – call connect() (or trigger the hosted button) to send the user into Mio’s consent flow.
  2. Receive the authorization code – Mio sends the browser back to your redirectUrl with a code query parameter.
  3. Call your exchange endpoint – the browser posts that code to your backend (for example /api/exchange-token).
  4. Swap for tokens – the backend calls mio.exchangeCodeForTokens(code) and stores the returned refreshToken securely (encrypted or in a secrets store).
  5. Use short-lived access tokens – pass the accessToken to getContext or getContextSummary whenever you need Mio Context.
  6. Refresh daily – access tokens expire after 24 hours; schedule calls to mio.refreshTokens(refreshToken) (or trigger them when you receive a 401) to mint fresh access tokens without asking users to reconnect.
Access tokens last 24 hours. Keep refresh tokens server-side only and plan a background job or on-demand handler that calls refreshTokens(refreshToken) before they expire.

​
Responsibilities at a glance

Client

Hosts buttons, callbacks, and any immediate feedback to the user. It only keeps short-lived state (e.g., “connected”).

Backend

Stores secrets, exchanges codes, refreshes tokens, and decides how to persist Mio context or trigger downstream jobs.

Mio Context

Receives authenticated requests, turns signals from tools like email and calendar into structured facts, and returns a tailored context object or summary you can plug into any workflow.

​
Security checkpoints

Keep your Mio client secret environment variable in a secret manager and never expose it to the browser.
Use HTTPS for redirect URLs, token exchange routes, and any endpoint that proxies Mio traffic.
Encrypt refresh tokens at rest, rotate them periodically, and keep them server-side so you can request new access tokens without prompting the user again.
Apply rate limiting or authentication to any proxy endpoint that forwards Mio Context lookups on behalf of thin clients.

​
Ready to build?

  • Read the Quickstart when you are ready to implement the browser → server → Mio Context flow.
  • Jump into the API reference for parameters, error codes, and advanced configuration once the basics work.