NorthlightSDK
Guides

Go live

Move an app from your laptop to a server you choose, and ask Northlight to verify it so anyone can sign in.

Northlight does not host your app's server. Deploy it wherever you like. What changes between your laptop and production is a short list.

Production checklist

  • A persistent connection store. MemoryConnectionStore loses every sign-in on restart and works for one process only. Use a store that survives restarts and locks across processes, such as PostgresConnectionStore from @north-light/sdk/stores/postgres, and pass it as store. Two processes that refresh the same connection with different stores race, and the directory refuses the loser with refresh_token_reused. The store holds credentials: restrict database access and encrypt backups.
  • The key file in a secret manager. The private key is the app's identity. Keep it out of git and out of images. Mount it where your host keeps secrets, and point CROUTER_KEY_FILE at that path (a container might read /run/secrets/app_key). The SDK reads no environment: your code loads the values and passes them to OAuth2Client.
  • A production redirect URI and origin. In the console, add https://<your domain>/auth/callback under Sign-in → Redirect URIs and set the Origin URL on the Profile tab to your domain. Set APP_ORIGIN to it on the server. Keep http://localhost:3000/auth/callback if you still develop locally.
  • An exact SDK pin. npm i --save-exact @north-light/sdk@<version>. A compatibility gate protects the wire between the SDK and Northlight's runtimes, not the TypeScript API, so a range or latest can pick up a type change on its next install. If a call fails with 426 runtime_version_unsupported, the SDK is newer than the runtimes: install the previous version or wait. To move on purpose, run npm view @north-light/sdk dist-tags and read the release notes for the versions in between.
  • One place for dead connections. Pass onRefusal to OAuth2Client, and schedule oauth.refreshIdleConnections so offline people stay connected. See Many users.
  • Redact sign-in secrets from logs. An authorization code and a refresh token in a log line is a credential. Keep them out of HTTP logs.
  • Listing, if you want it. In Profile → Marketplace, set a sign-in start URL and a text welcome, and turn on Listed in the marketplace. A testing app stays out of the marketplace.

Four variables configure an app built on the SDK:

VariableValue
CROUTER_ISSUERhttps://account.northlight.ai
CROUTER_CLIENT_IDThe client ID the console shows
APP_ORIGINYour app's origin. Its redirect URI is ${APP_ORIGIN}/auth/callback by convention
CROUTER_KEY_FILEPath to the private JWK; local/app-key.json by default

Let people other than your testers sign in

A new app is in testing: only you and up to 100 testers can sign in. To open it to everyone, ask Northlight to verify it by email to support@northlight.ai. Include your app's name and client ID, where it runs, and what it asks for and why. Until then, anyone else is refused with app_in_testing. See Testing mode.

This site does not state how long verification takes or what Northlight checks beyond that email address (not yet checked on production).

Rotate the key later

Add a second key, deploy with it, verify a real sign-in, then retire the old one. Rotation has no downtime. The steps are in Manage your app.

Manage your app

What each tab of the Northlight console does for an app you have registered, and the two things the console cannot do yet.

Providers

The first-party providers an app can call on a person's runtime, their ids, how scope strings are named, and how to list a provider's tools.

On this page

Production checklistLet people other than your testers sign inRotate the key later