Skip to main content

​
Initialization

src/lib/mio/server.ts
import { Mio } from '@mio-xyz/sdk/server';

export const mio = Mio.init({
  clientId: process.env.MIO_CLIENT_ID!,
  redirectUrl: process.env.MIO_REDIRECT_URL!,
  clientSecret: process.env.MIO_CLIENT_SECRET!
});
Mio.init is idempotent on the server. Call it during module evaluation or process startup and reuse Mio.getInstance() everywhere else.

​
Config parameters

​
clientId
string
required
OAuth application ID from the Mio dashboard.
​
redirectUrl
string
required
Absolute URL where Mio sends users back after the connection flow. Must match the redirect configured in Mio.
​
clientSecret
string
required
Confidential secret used only on the server when exchanging or refreshing tokens.

​
Methods

​
exchangeCodeForTokens(code: string): Promise<MioOauth2TokenResponse>

Swaps an authorization code for tokens using the confidential client credentials.
​
code
string
required
Authorization code provided by the Mio auth workflow.
​
response
MioOauth2TokenResponse
required
MioOauth2TokenResponse containing accessToken, refreshToken, expiresIn, tokenType, and idToken.
const tokens = await mio.exchangeCodeForTokens(code);
await userStore.save({
  accessToken: tokens.accessToken,
  refreshToken: tokens.refreshToken,
  expiresAt: Date.now() + tokens.expiresIn * 1000
});

{
  "accessToken": "atk_123",
  "refreshToken": "rtk_123",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
Errors include the underlying OAuth message. Log them before rethrowing so you can differentiate invalid_grant from network issues.

​
refreshTokens(refreshToken: string): Promise<MioOauth2TokenResponse>

Mint a new access token (and refresh token) without user interaction.
​
refreshToken
string
required
The token you persisted from the previous exchange.
​
response
MioOauth2TokenResponse
required
MioOauth2TokenResponse containing accessToken, refreshToken, expiresIn, tokenType, and idToken.
Access tokens expire after 24 hours. Schedule refreshTokens(refreshToken) before they expire (cron job, background worker, or on-demand when you receive a 401) and store the newly returned tokens.

​
getContext({ query, accessToken }): Promise<string>

Server-side wrapper that shares the same implementation as the client version. Use it when you run long operations or batch context requests on the backend.

​
Returns

​
response
string
required
The refined and personalized user summary, based on your query

​
getContextSummary({ accessToken }): Promise<string | null>

Retrieves the latest Mio Context summary for the given user.
​
response
string | null
required
Return the user summary if Mio has one, else return null.

​
Error matrix

MethodErrorDescription
exchangeCodeForTokensinvalid_grantRedirect URL or client credentials mismatch
exchangeCodeForTokensinvalid_requestMissing code body parameter
refreshTokensinvalid_grantExpired or revoked refresh token
getContext/getContextSummary401 UnauthorizedAccess token expired or malformed
All methods throw standard Error objects. Wrap calls with try/catch and map them to HTTP status codes that make sense for your API surface.