Quickstart

This guide gets you from an installed @secrecy/lib to an authenticated client and the current user. The code is plain TypeScript and does not depend on any UI framework: wire it into your application however you like.

Using JavaScript? The code is the same, just drop the type annotations.

Initialize the SDK

Call setup once, before any other SDK call. It loads the crypto library used to encrypt and decrypt on the user device.

secrecy.ts

import { setup } from '@secrecy/lib';
 
await setup();

Get an authenticated client

The getSecrecyClient function rebuilds a client from the credentials stored by a previous login. If there is none, the login function sends the user to the Secrecy SSO and brings them back to your application.

Keep a single client for the whole application: wrap it in a small module and import that module wherever you need the client.

secrecy.ts

import {
  getSecrecyClient,
  login,
  type SecrecyClient,
  setup,
} from '@secrecy/lib';
 
let client: SecrecyClient | null = null;
 
export const getClient = async (): Promise<SecrecyClient | null> => {
  if (client !== null) {
    return client;
  }
 
  await setup();
 
  // Reuse the credentials stored by a previous login, if any
  client = getSecrecyClient();
  if (client !== null) {
    return client;
  }
 
  // Otherwise, send the user to the Secrecy SSO.
  // With `redirect: true` the page is left and the promise resolves `null`;
  // on the way back, `getSecrecyClient` picks up the returned credentials.
  client = await login({
    appId: '<YOUR_APP_ID>',
    redirect: true,
    path: window.location.pathname,
    scopes: { email: true },
  });
 
  return client;
};

Fetch the current user

Once you have a client, client.me returns the signed-in user as a SelfUser.

user.ts

import type { SelfUser } from '@secrecy/lib';
 
import { getClient } from './secrecy';
 
export const getCurrentUser = async (): Promise<SelfUser | null> => {
  const client = await getClient();
  return client !== null ? await client.me() : null;
};

Integrating in your app

The SDK works the same whatever your stack. Keep these rules in mind when you wire it in:

Run it in the browser. login and getSecrecyClient use window and browser storage. If your application renders on the server, call them from code that only runs on the client.
Call setup before anything else. The getClient helper above does it for you.
Create the client once and share it. Use a module like secrecy.ts, your application state, or dependency injection, rather than creating a new client each time.
Handle the redirect back. After login({ redirect: true }), the user lands on path with the credentials in the URL. Calling getSecrecyClient on that page (as getClient does) consumes them.
Choose where the session lives. By default credentials are kept in localStorage and survive a browser restart. Pass { session: true } to both getSecrecyClient and login to keep them in sessionStorage instead.

Next steps

Secrecy auth: all login and getSecrecyClient options, the popup flow and logout.
Concepts: how sessions, identities and encryption fit together.
API reference: every class, function and type exported by @secrecy/lib.

Installation Sign-in & session