Identity API Reference

Crate provides a set of public APIs to integrate authentication flows into your application. These endpoints are split between Client-Side Endpoints (secured via your Publishable Key) and Backend RPCs (secured via your Secret Key).

[!NOTE] Management and settings operations (such as listing a user’s credentials or toggling identity settings) are reserved for the Crate Dashboard and are not exposed via the public API.

Client-Side Authentication (Publishable Key)

These endpoints are designed to be called directly from your frontend application (browser or mobile). They require your Publishable Key in the Authorization header.

Password Authentication

If you have enabled Password Authentication in your Identity Settings, you can use these endpoints to manage traditional login flows.

Register with Password

POST /identity/register/password

Registers a new user identity with a standard password.

Request Body:

{
  "identifier": "user@example.com",
  "password": "SecurePassword123!"
}

Login with Password

POST /identity/login/password

Authenticates an existing user via password.

Request Body:

{
  "identifier": "user@example.com",
  "password": "SecurePassword123!"
}

Reset Password

POST /identity/reset/password

Resets the password for a given Identity ID.

Request Body:

{
  "identity_id": "uuid-of-the-identity",
  "new_password": "NewSecurePassword456!"
}

WebAuthn (Passkeys)

While it is highly recommended to use the CrateIdentityJS SDK to handle Passkey ceremonies natively, you can interact with the raw endpoints if building a custom SDK.

• POST /identity/register/begin: Begins the WebAuthn registration ceremony.
• POST /identity/register/finish: Completes the WebAuthn registration.
• POST /identity/login/begin: Begins the WebAuthn assertion (login) ceremony.
• POST /identity/login/finish: Completes the WebAuthn login.

Backend Operations (Secret Key)

These endpoints are highly privileged and are implemented via Connect RPC. They require your Secret Key in the Authorization header and must only be called from a secure server environment.

Generate a Magic Link

POST /crate.v1.IdentityService/GenerateMagicLink

Generates a secure, one-time-use token for a given user identifier (e.g., email). You can then embed this token in a magic link sent via your preferred email or SMS provider.

Request Body:

{
  "identifier": "user@example.com"
}

Response:

{
  "token": "secure-magic-link-token"
}

Verify a Magic Link

POST /crate.v1.IdentityService/VerifyMagicLink

Consumes a magic link token and returns the authenticated identity_id.

Request Body:

{
  "token": "secure-magic-link-token"
}

Response:

{
  "identity_id": "uuid-of-the-identity"
}

Managing Passkeys

You can also programmatically manage a user’s passkeys from your backend via Connect RPC:

• POST /crate.v1.IdentityService/BeginAddPasskey: Starts the ceremony to add a new passkey to an existing identity.
• POST /crate.v1.IdentityService/FinishAddPasskey: Completes the addition of the new passkey.
• POST /crate.v1.IdentityService/RemovePasskey: Revokes a specific passkey credential from a user’s identity.