OAuth Provider - TinyCloud

Use OpenKey OAuth when your application needs OpenKey-issued identity tokens. This is separate from using an OpenKey key to sign in to TinyCloud.

Before you start: register a client

OAuth requires a client ID and an exact redirect URI. Client registration is currently an operator-managed boundary; there is no public self-service registration flow documented for the hosted service.

For hosted OpenKey, request a client through TinyCloud support.
For a self-hosted OpenKey deployment, an administrator can run this command from the OpenKey repository with OPENKEY_API_URL and ADMIN_API_KEY configured:

bun run oauth:register \
  --name "My App" \
  --type spa \
  --redirect-uri "http://localhost:5173/callback"

The current registration API creates public spa or native clients. These clients use PKCE and do not have a client secret.

Install the SDK

npm install @openkey/[email protected]

The SDK generates and stores the PKCE verifier, generates a state value, opens the authorization page, and validates the returned state before resolving connect().

import { OpenKey } from "@openkey/sdk";

const clientId = "ok_your_client_id";
const redirectUri = "http://localhost:5173/callback";
const openkey = new OpenKey({
  host: "https://openkey.so",
  oauthHost: "https://api.openkey.so",
  appName: "My App",
  mode: "popup",
});

const { code } = await openkey.oauth.connect({ clientId, redirectUri });
const tokens = await openkey.oauth.exchangeCode(code, {
  clientId,
  redirectUri,
});

console.log(tokens.access_token, tokens.expires_in);

The redirect URI must be registered even for popup mode: the popup navigates to that URI before the SDK reads the authorization response.

Redirect flow and callback

Redirect mode navigates the current page, so connect() does not resolve in the page that starts the flow.

const openkey = new OpenKey({ mode: "redirect" });
await openkey.oauth.connect({ clientId, redirectUri });

On the registered callback page, parse the response, verify state, and then exchange the code. Keep these operations in this order so an untrusted callback cannot consume the stored PKCE verifier.

import { OpenKey } from "@openkey/sdk";

const openkey = new OpenKey({ mode: "redirect" });
const callback = openkey.oauth.parseCallback();

if ("error" in callback) {
  throw new Error(callback.errorDescription ?? callback.error);
}
if (!openkey.oauth.verifyState(callback.state)) {
  throw new Error("OAuth state mismatch");
}

const tokens = await openkey.oauth.exchangeCode(callback.code, {
  clientId: "ok_your_client_id",
  redirectUri: "http://localhost:5173/callback",
});

Token lifecycle

Use expires_in from the token response instead of assuming a fixed access token lifetime.
Keep access tokens in memory when possible. Store refresh tokens only in protected server-side or platform credential storage.
refresh_token is optional. The current browser SDK requests the openid scope, so applications must not assume that a refresh token will be issued.
exchangeCode() removes its stored PKCE verifier after the exchange. Start a new authorization flow if the exchange must be retried with a new code.

The lower-level @openkey/core package exposes refreshAccessToken() for a client that has been issued a refresh token. If a refresh response includes a new refresh token, replace the old one.

If your goal is TinyCloud sign-in, use the TinyCloud integration instead of OAuth.

​Before you start: register a client

​Install the SDK

​Popup flow

​Redirect flow and callback

​Token lifecycle

Before you start: register a client

Install the SDK

Popup flow

Redirect flow and callback

Token lifecycle