ForjioHuudisIdentityPlugipayPaymentsStorlaunchE-commerceFulkrumaFulfilmentRiplloMarketingLinkSnapShort URLsPawpadoGPU streaming
LinkSnap Docs
⌘K

Authentication overview

LinkSnap doesn't have its own login system. We use Huudis — Forjio's shared identity provider — so you can use the same email and password (or Google, or Apple account) across LinkSnap, Plugipay, Storlaunch, Fulkruma, Pawpado, Catentio, and any other Forjio product.

If you've signed up for a Forjio product before, you can sign in to LinkSnap with that same account.

One identity, many products. Your Huudis account is yours, not LinkSnap's. We don't store your password — Huudis does. We just trust the bearer tokens Huudis issues us when you sign in.

How it works (the short version)

Sign-in is a standard OpenID Connect (OIDC) flow. The five steps are:

  1. You click Sign in on linksnap.com.
  2. LinkSnap redirects you to huudis.com/api/v1/oidc/authorize with a request to authenticate.
  3. You enter your email and password (or click Google/Apple) on Huudis.
  4. Huudis redirects you back to linksnap.com/callback with a one-time code.
  5. LinkSnap's backend exchanges the code for an access token, sets a secure cookie on your browser, and you're in.

You never see steps 2-4 visually; they happen in two HTTP redirects.

The two auth modes

LinkSnap uses bearer-token authentication in every place that needs a credential. There are exactly two ways a bearer token gets minted, and they share the same Huudis identity underneath:

Audience How a token is minted Where the token lives
Merchant signing into the portal OIDC authorization-code flow linksnap_session cookie (HMAC-signed, HTTP-only)
You, calling the API server-to-server Long-lived API key minted in the dashboard Whatever you put it in (env var, secret manager)
You, using the CLI on your terminal OIDC device flow — same Huudis identity, different transport ~/.config/linksnap/credentials.json

LinkSnap doesn't use HMAC request signing. If you've used the Plugipay docs, you'll see HMAC signing there because Plugipay handles money movement. LinkSnap uses a simpler Authorization: Bearer <token> scheme on every request — same as the OAuth standard.

The portal cookie, the API key, and the CLI session are independent. Revoking one doesn't affect the others.

What goes in the session cookie

The LinkSnap session cookie (linksnap_session) is a JWT signed with HMAC-SHA256 by LinkSnap's backend. It carries:

  • userId — your LinkSnap user record's ID (a local stub keyed to your Huudis identity).
  • workspaceId — the active workspace.
  • email, name — cached from Huudis for UI display.
  • huudisSub — your durable Huudis user ID.
  • huudisAccessToken — the access token used when LinkSnap needs to call Huudis APIs on your behalf.
  • huudisRefreshToken — used to mint new access tokens when the current one expires.

The cookie is httpOnly (no JavaScript can read it), Secure in production, and SameSite=Lax. It can't be inspected from the browser console.

API keys

For server-to-server access, mint an API key in the portal at Settings → API keys. Keys are workspace-scoped — one key, one workspace. They authenticate as a Bearer token:

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxx

Keys carry the full permission set of their workspace. There are no per-key scopes yet — treat the key the way you'd treat a workspace admin password. Rotate from the portal if exposed.

API keys never expire on their own; they live until you delete them. Revoke an unused key whenever you can.

CLI device flow

The linksnap CLI mints credentials over the OIDC device authorization flow (RFC 8628):

  1. linksnap auth login calls huudis.com/api/v1/oidc/device/authorize and gets a short user code.
  2. The CLI prints the code and opens the verification URL in your browser.
  3. You sign into Huudis (if not already) and approve the request.
  4. The CLI polls Huudis's token endpoint and saves the resulting tokens locally.

After login, subsequent commands attach the token as Authorization: Bearer <access>. The CLI refreshes the access token transparently when it expires.

See API → Authentication for the on-the-wire details.

Single sign-on across products

Because every Forjio product points at the same Huudis instance, you're already signed in to all of them once Huudis has an active session for you. Visit Plugipay after signing into LinkSnap — you skip the password screen.

You can sign out of one product without signing out of the others: each product owns its own session cookie. To sign out everywhere, sign out of Huudis itself.

Multi-workspace

A single Huudis identity can own (or be a member of) multiple LinkSnap workspaces. We treat each workspace as a tenant boundary — links, QR codes, API keys, and members are scoped to one workspace at a time.

After signing in you land in your active workspace. The dashboard's workspace switcher lets you change it; we store your last active choice in the session cookie.

What can go wrong

  • Email not verified. If you signed up via email and didn't click the verification link, you can't sign in. Re-request the link from the sign-in error screen.
  • Social provider not enabled. The Google and Apple buttons only appear when the Huudis instance has those providers configured. If a button is missing, fall back to email/password.
  • Forgot password. LinkSnap can't reset it — Huudis owns passwords. Follow the Forgot password flow.
  • Session expired. Cookies live for 7 days from sign-in. After that, you'll be sent back through the OIDC flow on your next page load. No data is lost — this is just a re-auth.

Next