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": (session_token: text) -> (IILoginBeginResult);

Returns a message to sign.

complete_self_custody_verification

Complete verification with signature.

"complete_self_custody_verification": (session_token: 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 valid for 1 year

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