Skip to main content
The Identity Plugin provides comprehensive identity management for the ICP Agent Kit, including seed phrase generation, anonymous identities, and secure storage.

​
Overview

The Identity Plugin manages cryptographic identities for interacting with the Internet Computer. It supports:
  • Seed Phrase Identities: Create identities from BIP39 mnemonic phrases
  • Anonymous Identities: For testing and privacy-focused applications
  • Identity Switching: Seamlessly switch between multiple identities
  • Secure Storage: In-memory identity management with proper cleanup

​
Methods

​
generateSeedPhrase(wordCount?)

Generate a new BIP39 mnemonic seed phrase. Parameters:
  • wordCount (optional): 12 | 24 - Number of words (default: 12)
Returns: string - Generated seed phrase Example: 
const seedPhrase12 = agent.identityPlugin.generateSeedPhrase();
const seedPhrase24 = agent.identityPlugin.generateSeedPhrase(24);

​
createFromSeedPhrase(seedPhrase, key?)

Create an identity from a seed phrase. Parameters:
  • seedPhrase: string | string[] - BIP39 mnemonic phrase
  • key (optional): string - Unique key for the identity (auto-generated if not provided)
Returns: Promise<IIdentityCreationResult>
  • identity: Secp256k1KeyIdentity - Created identity
  • info: IIdentityInfo - Identity information
Example: 
const result = await agent.identityPlugin.createFromSeedPhrase(
  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
  'my-main-wallet'
);

console.log('Principal:', result.info.principal.toText());
console.log('Account ID:', result.info.accountId);

​
createAnonymous(key?)

Create an anonymous identity. Parameters:
  • key (optional): string - Unique key for the identity (auto-generated if not provided)
Returns: Promise<IIdentityCreationResult> Example: 
const result = await agent.identityPlugin.createAnonymous('test-identity');
console.log('Anonymous identity created:', result.info.isAnonymous);

​
switch(key)

Switch to a different identity. Parameters:
  • key: string - Key of the identity to switch to
Returns: Promise<void> Example: 
await agent.identityPlugin.switch('my-main-wallet');
console.log('Switched to:', agent.identityPlugin.getCurrentKey());

​
remove(key)

Remove an identity from storage. Parameters:
  • key: string - Key of the identity to remove
Returns: void Example: 
agent.identityPlugin.remove('old-identity');

​
list()

Get a list of all stored identity keys. Returns: string[] - Array of identity keys Example: 
const identities = agent.identityPlugin.list();
console.log('Available identities:', identities);

​
getCurrentKey()

Get the key of the currently active identity. Returns: string - Current identity key Example: 
const currentKey = agent.identityPlugin.getCurrentKey();
console.log('Current identity:', currentKey);

​
getInfo()

Get detailed information about the current identity. Returns: Promise<IIdentityInfo>
  • type: IdentityType - Type of identity (secp256k1, anonymous)
  • principal: Principal - Identity principal
  • accountId: string - ICP account identifier
  • isAnonymous: boolean - Whether identity is anonymous
Example: 
const info = await agent.identityPlugin.getInfo();
console.log('Identity type:', info.type);
console.log('Principal:', info.principal.toText());
console.log('Account ID:', info.accountId);

​
getPrincipal()

Get the principal of the current identity. Returns: string - Principal as string Example: 
const principal = agent.identityPlugin.getPrincipal();
console.log('Current principal:', principal);

​
getAccountId()

Get the ICP account identifier of the current identity. Returns: string - Account identifier Example: 
const accountId = agent.identityPlugin.getAccountId();
console.log('Account ID:', accountId);

​
Types

​
IIdentityCreationResult

Result of identity creation operations. 
interface IIdentityCreationResult {
  identity: Identity;
  info: IIdentityInfo;
}

​
IIdentityInfo

Detailed information about an identity. 
interface IIdentityInfo {
  type: IdentityType;
  principal: Principal;
  accountId: string;
  isAnonymous: boolean;
}

​
IdentityType

Type of identity. 
type IdentityType = 'secp256k1' | 'anonymous';

​
Usage Patterns

​
Multi-Wallet Management

// Generate seed phrases for different wallets
const mainWallet = agent.identityPlugin.generateSeedPhrase();
const tradingWallet = agent.identityPlugin.generateSeedPhrase();

// Create identities
await agent.identityPlugin.createFromSeedPhrase(mainWallet, 'main');
await agent.identityPlugin.createFromSeedPhrase(tradingWallet, 'trading');

// Switch between wallets
await agent.identityPlugin.switch('main');
console.log('Main wallet principal:', agent.identityPlugin.getPrincipal());

await agent.identityPlugin.switch('trading');
console.log('Trading wallet principal:', agent.identityPlugin.getPrincipal());

​
Development with Anonymous Identities

// Create anonymous identity for testing
await agent.identityPlugin.createAnonymous('test');
await agent.identityPlugin.switch('test');

const info = await agent.identityPlugin.getInfo();
if (info.isAnonymous) {
  console.log('Using anonymous identity for testing');
}

​
Identity Lifecycle Management

// List all identities
const identities = agent.identityPlugin.list();
console.log('Available identities:', identities);

// Get current identity info
const current = agent.identityPlugin.getCurrentKey();
const info = await agent.identityPlugin.getInfo();

console.log(`Current: ${current}`);
console.log(`Type: ${info.type}`);
console.log(`Principal: ${info.principal.toText()}`);

// Clean up old identities
if (identities.includes('old-test-identity')) {
  agent.identityPlugin.remove('old-test-identity');
}

​
Security Considerations

  1. Seed Phrase Storage: Never log or expose seed phrases. Store them securely outside the application.
  2. Identity Cleanup: Use agent.destroy() to properly clean up identities when done.
  3. Anonymous vs Secp256k1: Use anonymous identities only for testing. Use secp256k1 identities for production applications.
  4. Principal Validation: Always validate principals before using them in operations.

​
Error Handling

import { ICPAgentError } from 'icp-agent-kit';

try {
  await agent.identityPlugin.createFromSeedPhrase('invalid seed phrase');
} catch (error) {
  if (error instanceof ICPAgentError) {
    if (error.code === 'IDENTITY_CREATION_FAILED') {
      console.log('Failed to create identity:', error.message);
    }
  }
}