Manage your app

You manage an app in the console at https://account.northlight.ai/console. Choose your app in the list to open its page. The tabs are Sign-in, What it asks for, Profile, Sharing, Testers and Provider. (Only the first-party apps use Provider.)

Your client ID is shown on the app's page. Copy it into CROUTER_CLIENT_ID, or write it to local/app.env with npx @north-light/sdk env --client-id <client id>.

Sign-in

• Redirect URIs. Sign-in returns only to a URI listed here, matched exactly: localhost and 127.0.0.1 are different URIs, and the port counts. Each sign-in names the URI to return to, so an app can hold several (for example your deployed callback and a localhost one). Save redirect URIs replaces the whole list, so keep the ones you still use.
• Keys. An app proves who it is with a signing key. There is no client secret. Add a key takes a public JWK; the form refuses a pasted private key. You can instead Use a JWKS URL: the directory reads the keys from that URL. An app holds at most 2 active keys. Retire stops a key signing in; a retired key can be Deleted so it can be added again.

Rotate a key

Rotating has no downtime, because the directory accepts a sign-in signed by either active key.

1. Generate the new key beside the current one: npx @north-light/sdk keygen --out local/app-key.next.json. It prints the public JWK.
2. In Sign-in → Keys, choose Add a key and paste the JWK. Both keys are now active.
3. Point CROUTER_KEY_FILE (or your privateKey) at local/app-key.next.json and deploy.
4. Complete one real sign-in through the callback, or refresh a stored connection. Opening your login route only redirects to the directory and never reaches the token endpoint, so it proves nothing about the key.
5. Retire the old key, then delete the old key file.

Until you retire the old key it is your rollback. After you retire it, a sign-in signed with it fails with unauthorized, and the message names the key as retired. An app registered with a JWKS URL rotates the same way through the URL: publish the new key beside the old one, switch, verify, then remove the old one. The directory re-reads the URL within about a minute.

What it asks for

• What your app asks for. The scopes people are asked to approve. Add permissions searches the catalog; take scope strings from it and from providers.tools, and do not invent them. crtr:act needs crtr:llm. See Scopes and grants.
• What your app requires. Providers the app cannot work without. A person is taken through that provider's setup the first time they sign in. See Grant changes.
• Monthly spend cap. The most your app may spend of each person's AI subscription per month, in whole US dollars.

Profile

• How people see your app: Name, Origin URL, Logo URL, and Why your app needs access (quoted on the consent page as your words). Save details.
• Marketplace: Listed in the marketplace, Price, Sign-in start URL and Text welcome. Agents can install a listed app for a person by text. A testing app stays out of the marketplace even when listed. The sign-in start URL is where Install sends people; your /auth/login route is a valid one, and a localhost URL is accepted. The text welcome is one or two plain sentences, at most 120 characters, with no links.

Testers

A new app is in testing: only you and up to 100 testers can sign in. Add a tester by the email or phone number on their Northlight account. An email matches only while it is verified on that account. Nobody gets a message, so tell them. Removing a tester revokes their grant for the app. See Testing mode.

Sharing

What other apps may use lists parts of your app's space (memory, files, conversations) that other apps may ask for, and at what access (read or read/write). Add a folder to share a part of your app's files.

Develop beside a live app

Once your app is live you can keep developing on your laptop against production while the live app keeps running. There are two ways.

Add your localhost callback to the live app. This is simplest and fine for most apps. In Sign-in → Redirect URIs, list both https://app.example.com/auth/callback and http://localhost:3000/auth/callback. Give your laptop its own signing key beside the deployed one (an app holds at most 2 active keys), so you never copy the production private key to your laptop. Both servers share the same people, grants, space and scopes. A scope you add while developing changes what the live app asks of everyone. The origin, sign-in start URL and run notice URL each hold one value, so they keep pointing at the deployed app.

Register a separate development app. Do this when you are changing what the app asks for, or need grants and data that live people never touch. Register another app in the console, for example "Texty (dev)", with a localhost origin and redirect URI and its own key. It starts in testing and stays there, so only you and your testers can sign in, and it never appears in the marketplace. Point your laptop's environment file at its client ID.

Two things the console can't do yet

Deleting an app and setting its run notice URL are not in the console today. Both need crtr, the Northlight command line, on a machine joined to your Northlight account. Joining is a one-time setup described in the crouter docs: install @north-light/cli, then run crtr sys join with a token from https://account.northlight.ai/account/machines. Joining rewrites the local crtr home and has no unjoin, so join from a home you can throw away. These steps are the only part of building an app that needs crtr.

Delete an app

crtr cloud apps delete --app-id <client id> --confirm <client id>

It answers deleted: true and removed_grants, the number of people's grants it removed. Each person's runtime deletes the app's runs, space and schedules, and the app's next refresh fails with invalid_grant. The app's key stops working, its page answers 404 and it disappears from your list. This cannot be undone. You must run it yourself in the terminal of the joined machine: an agent, including your chat agent, is refused with provider_refused. If you only want a clean slate for tests, changing the app's redirect URIs and keys is often simpler.

Set the run notice URL

crtr cloud apps set-run-notice-url --app-id <client id> --url https://app.example.com/run-notices
crtr cloud apps set-run-notice-url --app-id <client id> --clear

The URL must be https (plain http only on localhost in development) and at most 512 characters. What the app does with notices is in Background runs.