Anythink SDK: sign-in and sessions

The Anythink SDK (@anythink-cloud/sdk) handles sign-in and sessions for a React app that talks to your project's REST API. It signs users in with email and password, stores the session, refreshes the access token before it matters, and attaches the token to your API calls.

The SDK is auth-only. It does not read or write your entities, and it has no realtime, GraphQL or functions layer. For data you call the REST API with the token the SDK manages.

How sessions work#

Signing in exchanges an email and password for a session: an access token, a refresh token and the access token's lifetime.

Refresh tokens are single-use. Each refresh returns a new access token and a new refresh token and revokes the old refresh token. Signing out revokes the refresh token on the server too.

The SDK keeps the session in a store and persists it in the browser (see Choose where the session is stored). Its lifecycle is:

1. signIn posts the credentials, stores the session, then loads the user from GET /org/{project_id}/users/me.
2. AuthenticatedBaseService attaches the access token to each request.
3. When a request returns 401, the service calls refreshSession, then replays the request once with the new token. Concurrent refreshes share one network call, so a burst of failing requests makes one refresh, not many.
4. If the refresh fails, the session is cleared and the original 401 is returned to your code.
5. On page load, AuthProvider restores the stored session. It refreshes an expired one, and sends the user to your login page if there is no valid session.

Set up your project#

Before the SDK can sign anyone in, your project needs to allow your app's address and, if users register themselves, allow registration. You also need two values: your project ID and the API URL.

Install and create the client#

npm install @anythink-cloud/sdk

React 18 or 19 is a peer dependency. Create one AuthClient for the whole app and reuse it. Each client keeps its own session store, so two clients in one page don't share state.

import { AuthClient } from "@anythink-cloud/sdk";

let client: AuthClient | null = null;

export const getAuthClient = (): AuthClient => {
  if (!client) {
    client = new AuthClient({
      instanceUrl: "https://api.my.anythink.cloud",
      orgId: 12345678,
      storageType: "localStorage",
      cookieStorage: { name: "orders_app_session" },
    });
  }
  return client;
};

orgId is your project ID. cookieStorage.name is the key the session is saved under, whichever storage you pick. Give each app its own name so apps on the same domain don't overwrite each other.

Add the provider#

Wrap your app in AuthProvider.

import { AuthProvider } from "@anythink-cloud/sdk";
import { getAuthClient } from "./authClient";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider
      authClient={getAuthClient()}
      loginUrl="/auth/login"
      authPrefix="/auth"
      callbacks={{
        onSignIn: (session) => console.log("signed in", session.expires_at),
        onSignOut: () => console.log("signed out"),
        onTokenRefreshFailed: () => console.log("session expired"),
      }}
    >
      {children}
    </AuthProvider>
  );
}

onSignOut runs every time the provider signs the user out, including when it finds no session on load and redirects to loginUrl.

Sign users in#

useAuth returns the session, the user and the actions. Failed calls don't throw: signIn, register, refreshSession, signOut and changePassword resolve with an error field, so check it rather than wrapping the call in try/catch.

import { useState } from "react";
import { useAuth } from "@anythink-cloud/sdk";

export function LoginForm() {
  const auth = useAuth();
  const [error, setError] = useState<string | null>(null);

  async function onSubmit(email: string, password: string) {
    setError(null);
    const result = await auth.signIn(email, password);
    if (result.error || !result.data.session) {
      setError(result.error?.message ?? "Sign-in failed");
      return;
    }
    window.location.href = "/";
  }

  // render your form and call onSubmit
}

On failure, error.message is the message from the API. The ones you'll handle most often:

Register a user#

const { error } = await auth.register("Ada", "Lovelace", "ada@example.com", "Sup3r-secret!");

register creates the user but doesn't sign them in. If the project requires email confirmation, Anythink emails a confirmation link, and the user can sign in once they've confirmed. Otherwise call signIn straight away.

Passwords need at least eight characters, with an upper-case letter, a lower-case letter, a digit and a special character. First and last names are limited to 50 characters. Registration fails with the API's message if the project doesn't allow registrations or has no default role set.

Sign in with a social provider#

Social sign-in doesn't go through signIn. Run the flow described in Social sign-in with Apple, Google, GitHub and LinkedIn, then hand the tokens it returns to the SDK:

await getAuthClient().setSession({
  access_token,
  refresh_token,
  expires_in,
});

setSession stores the session and loads the user, and from then on refresh and API calls work exactly as they do after signIn.

Sign out and change the password#

await auth.signOut();
await auth.changePassword("current-password", "N3w-secret-pass!");

signOut clears the local session first, so it succeeds even if the server call fails, and then revokes the refresh token on the server. changePassword calls /org/{project_id}/users/me/password with the current access token.

Read the session and the user#

const { session, user, isAuthenticated, isLoading, error } = useAuth();

Outside React, the same data is on the client: getSession(), getUser(), getAccessToken(), getRefreshToken() and isAuthenticated(). fetchUserInfo() reloads the user from the API.

Call the REST API#

Extend AuthenticatedBaseService for each group of calls. It gives you an Axios client that sends the access token, refreshes on 401 and replays the request.

import { AuthenticatedBaseService } from "@anythink-cloud/sdk";
import { getAuthClient } from "./authClient";

const API_URL = "https://api.my.anythink.cloud";
const ORG_ID = 12345678;

export type Order = { id: number; status: string; total: number };

class OrderService extends AuthenticatedBaseService {
  constructor() {
    super(getAuthClient(), API_URL);
  }

  async list(): Promise<Order[]> {
    const res = await this.get<{ items: Order[] }>(
      `/org/${ORG_ID}/entities/orders/items`
    );
    return res.items;
  }
}

export const orders = new OrderService();

The helpers get, post, put, patch, delete and postFormData return the response body. getClient() returns the underlying Axios instance if you need it. The calls are subject to the signed-in user's role permissions and row-level security, the same as any other API request.

Choose where the session is stored#

storageType decides where the session persists.

With "cookie" you can also set cookieStorage.domain, path (default /), secure (default on over HTTPS) and sameSite (default lax).

Only the session and the user are persisted. Loading and error state live in memory.

Point the client at other endpoints#

By default the client calls these paths, with your project ID in place of {project_id}:

tokenEndpoint, refreshEndpoint, logoutEndpoint, registerEndpoint and changePasswordEndpoint in the config replace the sign-in, refresh, sign-out, register and change-password paths. Use them if you proxy sign-in through your own server. The responses must keep the same shape: access_token, refresh_token and expires_in.

Without the SDK#

The SDK is a thin layer over these endpoints, so any client can use them directly. Sign in with POST /org/{project_id}/auth/v1/token, refresh with POST /org/{project_id}/auth/v1/refresh, and send the access token as Authorization: Bearer …. For server-to-server calls use an API key instead of a user session.

Limits and trade-offs#

Next steps#