Getting Started & Setup

Setting up the Crate Identity System takes just a few minutes. This guide covers how to enable the module in your Crate Console, install the necessary SDKs, and initialize them in your application.

1. Prerequisites: Enabling Identity

Before integrating the code, you must explicitly enable the Identity module for your organization.

1. Log into the Crate Console.
2. Navigate to Organization Settings > Billing & Modules.
3. Under Main Modules, check the box for the Identity System.
4. Save your changes. The Identity tab will now appear in your sidebar navigation.

2. SDK Installation

The Identity System relies on two integration points to maintain strict security boundaries: a frontend SDK for client-side interactions (like Passkeys) and server-side REST API calls for privileged operations (like generating Magic Links).

Frontend SDK

Install the CrateIdentityJS SDK in your client application directly from the Crate GitLab instance.

If using a Node.js package manager:

npm install git+https://gitlab.com/cratecc/identity-js.git
# or
yarn add git+https://gitlab.com/cratecc/identity-js.git

If using Deno (like in the Crate App), you can map the import in your deno.json directly to the raw ESM URL:

{
  "imports": {
    "@cratecc/identity-js": "https://gitlab.com/cratecc/sdk/-/raw/main/js/packages/identity-js/mod.ts"
  }
}

Backend Integration

Currently, backend operations are performed via direct REST API calls rather than a dedicated SDK. You can use standard HTTP clients like fetch or axios in your secure server environment.

3. Initialization

Once installed, configure your frontend SDK and prepare your backend API requests.

Frontend Initialization

Import and initialize the client SDK at the root of your application. You only need your Public Client ID for this step.

import { CrateIdentity } from '@crate/identity-js';

const identityClient = new CrateIdentity({
  clientId: process.env.NEXT_PUBLIC_CRATE_CLIENT_ID,
  environment: 'production' // or 'sandbox'
});

export default identityClient;

Backend API Integration

Since backend operations are highly privileged, make sure you perform them in a secure server environment (e.g., API routes, serverless functions) using your Secret Key. Never expose this key to the client.

Here is an example of calling the Crate Identity API to generate a Magic Link using standard fetch:

// Example usage: Generate a Magic Link
const generateMagicLink = async (email) => {
  const response = await fetch('https://api.crate.cc/crate.v1.IdentityService/GenerateMagicLink', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.CRATE_SECRET_KEY}`
    },
    body: JSON.stringify({ email })
  });
  
  const data = await response.json();
  return data.link;
};

You are now ready to implement specific authentication flows! Head over to the Authentication guide to get started.