identity-gateway API

Internet Identity integration canister for passwordless authentication and device management.

Candid file: identity-gateway/src/identity_gateway.did

Types

SessionTokens

type SessionTokens = record {
  access_token: text;
  refresh_token: text;
};

DeviceRecord

type DeviceRecord = record {
  device_id: text;
  device_name: text;
  registered_at: nat64;
  last_used_at: nat64;
  is_active: bool;
};

Result Types

type IILoginBeginResult = variant {
  Ok: text;   // Challenge/nonce
  Err: text;
};

type IILoginCompleteResult = variant {
  Ok: SessionTokens;
  Err: text;
};

type LinkResult = variant {
  Ok;
  Err: text;
};

Internet Identity Authentication

ii_login_begin

Start Internet Identity login flow.

"ii_login_begin": () -> (IILoginBeginResult);

Returns a challenge/nonce for the II delegation.

ii_login_complete

Complete II login with delegation chain.

"ii_login_complete": (delegation_chain: text) -> (IILoginCompleteResult);

TypeScript Example:

import { AuthClient } from '@dfinity/auth-client';

// Initialize auth client
const authClient = await AuthClient.create();

// Start II flow
const beginResult = await identityGatewayActor.ii_login_begin();
if ('Err' in beginResult) throw new Error(beginResult.Err);

// User authenticates with II
await authClient.login({
  identityProvider: 'https://identity.ic0.app',
  onSuccess: async () => {
    const identity = authClient.getIdentity();
    const delegation = identity.getDelegation().toJSON();

    // Complete login
    const completeResult = await identityGatewayActor.ii_login_complete(
      JSON.stringify(delegation)
    );

    if ('Ok' in completeResult) {
      const { access_token, refresh_token } = completeResult.Ok;
      // Store tokens
    }
  }
});

Account Linking

link_internet_identity

Link II to existing email/password account.

"link_internet_identity": (session_token: text, ii_delegation: text) -> (LinkResult);

Requirements:

• Valid session token from email/password login
• II must not be linked to another account

unlink_internet_identity

Remove II link from account.

"unlink_internet_identity": (session_token: text) -> (LinkResult);

Self-Custody Verification

For governance participation, members must verify they control their own wallet.

begin_self_custody_verification

Start verification flow.

"begin_self_custody_verification": (caller_user_id: text) -> (IILoginBeginResult);

Returns a message to sign.

complete_self_custody_verification

Complete verification with signature.

"complete_self_custody_verification": (caller_user_id: text, signature: text) -> (LinkResult);

Flow:

1. Call begin_self_custody_verification to get message
2. User signs message with their II
3. Submit signature to complete_self_custody_verification
4. Verification is valid for 90 days. Governance participation requires a current (non-expired) self-custody verification, so a member must re-verify before the 90-day window elapses.

get_self_custody_status (query)

Read the current self-custody verification status for an II principal.

"get_self_custody_status": (ii_principal: text) -> (SelfCustodyStatusResult) query;

Returns whether the principal is currently verified, the time it was verified, and the expiry (90 days after verified_at). A principal that has never verified returns a verified = false status rather than an error.

Device Management

get_user_devices (query)

Get all registered devices for a user.

"get_user_devices": (user_id: text) -> (GetDevicesResult) query;

type GetDevicesResult = variant {
  Ok: vec DeviceRecord;
  Err: text;
};

revoke_device

Revoke a specific device.

"revoke_device": (session_token: text, device_id: text) -> (LinkResult);

revoke_all_devices_except

Revoke all devices except current one (security lockout).

"revoke_all_devices_except": (session_token: text, current_device_id: text) -> (LinkResult);

Configuration (Controller Only)

set_auth_service

Configure auth-service canister.

"set_auth_service": (principal) -> (SetAuthServiceResult);

set_user_service

Configure user-service canister.

"set_user_service": (principal) -> (SetUserServiceResult);

Health Check

health (query)

"health": () -> (text) query;

sessions_count (query)

"sessions_count": () -> (nat64) query;

Error Messages

Error	Cause	Resolution
Invalid delegation	Delegation chain invalid	Re-authenticate with II
II already linked	This II linked to another account	Use different II anchor
Account not found	Session doesn't map to account	Check session valid
Device not found	Device ID doesn't exist	Check device registered
Verification expired	Self-custody verification too old	Re-verify