Internet Computer

What is a principal, and how does Internet Identity sign people in?

All help topics

A principal is the Internet Computer's identifier for whoever makes a call (a person, a CLI identity or a canister), and Internet Identity gives each person a different principal for each web address they sign in at.

Principals
  • Every call carries its caller's principal. A canister reads it (caller in Motoko, msg_caller() in Rust) to decide who may do what.
  • Unsigned calls come from the anonymous principal. Reject it wherever a real user is required.
  • Canisters have principals too (their canister id), so a canister can call another canister or control it.
  • On a cloud engine, access works by principal: the engine's team, each canister's controllers and who may deploy are all lists of principals.
Internet Identity
  • Internet Identity (II, at id.ai) is the Internet Computer's sign-in. People use a passkey on their device, a Google, Apple or Microsoft account, or their organization's sign-in. There are no passwords.
  • II derives a different principal for every origin a person signs in at. That prevents tracking across apps, and it means the console, each of your apps and each domain see different principals for the same person.
What that means for your apps
  • An app reached at its canister address and at a custom domain would see the same person as two users. Pin the app's derivation origin to its frontend canister's address (https://CANISTER_ID.icp.net) and list its other domains in /.well-known/ii-alternative-origins (at most 100 entries).
  • Decide this before people sign up: accounts already created under one origin can't be moved.
  • Renaming an engine changes its domain, so an app that signs people in at the engine's domain sees them as new users after a rename, unless it pins its derivation origin this way.
Signing the icp CLI in
  • To deploy, the CLI must sign as the same principal you use in the console. Copy the link command from the console's Connect your ICP CLI dialog rather than writing your own: a different --auth or --app value derives a different principal, which the engine refuses.
  • The command opens a sign-in in your browser, so your terminal and browser must be on the same computer.
  • On first use, II may say CLI access is turned off: turn it on in your II settings and run the command again.
  • icp identity principal shows which principal the CLI signs as. The link is time-limited; when it lapses, icp identity reauth with the identity's name signs in again.
Learn more
Still stuck? Contact support