Principal

Following a successful registration or authentication operation, your frontend code will receive a code and id_token (JWT). The code can be exchanged for an ExtendedPrincipal, while the id_token can be verified locally to obtain a Principal.

export interface Principal {
  _tag: "Principal";
  id: string;
  userId: string;
  authenticatorId: string;
  authenticatorType: "passkey";
  passkey?: {
    verified: boolean;
    userVerified: boolean;
  };
  createdAt: number;
  expiresAt: number;
}

Properties

Property	description
_tag	Discriminator, always `"Principal"`
id	Generated every time a Principal is created. Equivalent to the JWT jti property
userId	Assigned user ID. By default this matches the authenticatorId, but it only becomes an application-specific account ID if you explicitly assign it that way. See linking accounts
authenticatorId	Unique identifier i.e. the passkey ID. This is the default key to use when linking Passlock passkeys to local user accounts
authenticatorType	Currently hardcoded as “passkey”, but in the future this will be extended to support additional authenticator types e.g. Apple and Google sign-in
passkey.verified	Should always be true
passkey.userVerified	Whether the device re-authenticated the user locally
createdAt	Timestamp, milliseconds since epoch
expiresAt	Timestamp, milliseconds since epoch. Derived from the JWT `exp` property

Extended principal

If you obtain a Principal via the code exchange flow, you will receive an ExtendedPrincipal which includes some additional properties. Like Principal, it is tagged, so _tag will be "ExtendedPrincipal".

Property	description
_tag	Discriminator, always `"ExtendedPrincipal"`
metadata	Request metadata captured during the registration or authentication operation
passkey.platformName	The platform/ecosystem used to create the passkey e.g. Apple iCloud
metadata.ipAddress	IP address of the client using the passkey
metadata.userAgent	Client user agent