/
OAuth — Authorization Code Grant (apps)

OAuth — Authorization Code Grant (apps)

Authorization Code Grant lets a third-party application access your whole pico mesh — the root and all descendant picos — after you approve it with your passkey. Typical examples include Home Assistant and other dashboards or integrators that need more than one channel.

For a single webhook channel, use Client Credentials instead.

What you set up

  1. Install io.picolabs.oauth on the root pico (Rulesets tab).

  2. Set PICO_ENGINE_BASE_URL to the URL users reach in the browser (important for sign-in and redirects).

  3. Open Settings → OAuth apps, register the integrator (name, redirect URIs, public vs confidential client).

  4. Copy the app_… client ID (and client secret if not a public client) into the integrator’s configuration.

That registration is one-time admin setup. The integrator does not register itself on your engine.

What the user sees

When the integrator needs access:

  1. It opens the engine’s authorize page in the browser.

  2. If you’re not signed in, you sign in with your passkey.

  3. You see Authorize application — app name, scope, redirect target — and choose Allow or Deny.

  4. The browser returns to the integrator, which completes setup on its side and can call /sky/* on picos in your mesh.

You stay in control: only a signed-in account for that root mesh can approve. You can remove the app anytime in Settings → OAuth apps.

What the integrator gets

  • Access to /sky/* on channel ECIs anywhere under your root (not a single webhook channel).

  • Not access to /c/* (internal/UI API) — passkeys and sessions are for humans using the engine UI.

Channel policy still applies after the token is validated.

Webhook channels with Client Credentials continue to work separately; a webhook token does not replace app authorization, and an app token does not replace per-channel webhook credentials.

Public vs confidential client

Type

Typical use

Secret?

Type

Typical use

Secret?

Public (PKCE)

Home Assistant, native/SPA apps

No — PKCE at authorize/token time

Confidential

Server-side app that can store a secret

Yes — shown once at registration

Most integrators should be registered as public clients.

Revoking access

  • Settings → OAuth apps → Remove — revokes the app and its tokens.

  • Removing io.picolabs.oauth from the root unlocks the mesh for open channels but is a separate decision from app registration.

Troubleshooting

Integrator says OAuth is not enabled
Install io.picolabs.oauth on the root.

Authorize page asks you to sign in and then stops
Sign in with your passkey and try connecting again from the integrator.

Integrator connected but API calls fail
Confirm the integrator uses /sky/*, the engine URL is correct, and the ECI is a pico in your mesh.

For HTTP details (authorize URL, token exchange, PKCE, refresh)
See the engine README OAuth section or your integrator’s setup guide.