Examples¶

Practical code examples for integrating with the 5N ID SDK and REST API.

SDK Examples¶

Basic Connection¶

import { idSdk } from '@fivenorth/id-sdk';

// Connect to devnet
const connection = await idSdk.connect({
  clientId: process.env.ID_CLIENT_ID!,
  clientSecret: process.env.ID_CLIENT_SECRET!,
  network: 'devnet'
});

console.log('Connected to 5N ID service');

Create Credentials Request¶

// Request credentials for a party
const request = await connection.createCredentialsRequest({
  partyId: 'party::alice',
  providers: ['provider1', 'provider2']
});

console.log(`Request ID: ${request.requestId}`);
console.log(`Status: ${request.status}`);

List All Credentials¶

// Get all credentials with pagination
let offset = 0;
const limit = 20;
let allCredentials = [];

while (true) {
  const response = await connection.getCredentials({ offset, limit });
  allCredentials = allCredentials.concat(response.credentials);

  if (response.credentials.length < limit) {
    break; // Last page
  }

  offset += limit;
}

console.log(`Total credentials: ${allCredentials.length}`);
allCredentials.forEach(cred => {
  console.log(`- ${cred.contractId}: ${cred.partyId} (${cred.status})`);
});

Get Credentials for Specific Party¶

try {
  const credential = await connection.getCredentialsByPartyId('party::alice');
  console.log(`Contract ID: ${credential.contractId}`);
  console.log(`Status: ${credential.status}`);
  console.log(`Created: ${credential.createdAt}`);
} catch (error) {
  console.error('Credential not found:', error);
}

Generate Verification Link¶

// Generate a single verification link
const link = await connection.generateVerificationLink({
  contractId: 'contract_123'
});

console.log(`Verification link: ${link.link}`);
console.log(`Token: ${link.token}`);
console.log(`Expires at: ${link.expiresAt}`);

// Share this link with the user for verification

Generate Multiple Verification Links¶

// Generate links for multiple credentials at once
const links = await connection.generateVerificationLinksBatch({
  requests: [
    { contractId: 'contract_123' },
    { contractId: 'contract_456' },
    { contractId: 'contract_789' }
  ]
});

links.links.forEach(link => {
  console.log(`${link.contractId}: ${link.link}`);
});

Check Verification Status¶

// Check if a verification token has been used
const token = 'verify_token_abc123';
const status = await connection.checkVerificationStatus(token);

if (status.status === 'verified') {
  console.log(`Credential ${status.contractId} verified for party ${status.partyId}`);
  console.log(`Verified at: ${status.verifiedAt}`);
} else {
  console.log('Verification pending or not found');
}

Get Human Score¶

// Get identity verification score
const score = await connection.getHumanScore();

console.log(`Total Score: ${score.totalScore}/100`);

console.log('\nBadges:');
score.badges.forEach(badge => {
  const icon = badge.status === 'verified' ? '✓' : '✗';
  console.log(`  ${icon} ${badge.name}: ${badge.status}`);
});

console.log('\nBreakdown:');
if (score.breakdown.identity) {
  console.log(`  Identity: ${score.breakdown.identity}/100`);
}
if (score.breakdown.document) {
  console.log(`  Document: ${score.breakdown.document}/100`);
}
if (score.breakdown.biometric) {
  console.log(`  Biometric: ${score.breakdown.biometric}/100`);
}

Complete Workflow Example¶

import { idSdk } from '@fivenorth/id-sdk';

async function verifyPartyIdentity(partyId: string) {
  // 1. Connect to the service
  const connection = await idSdk.connect({
    clientId: process.env.ID_CLIENT_ID!,
    clientSecret: process.env.ID_CLIENT_SECRET!,
    network: 'devnet'
  });

  // 2. Check if credentials already exist
  let credential;
  try {
    credential = await connection.getCredentialsByPartyId(partyId);
    console.log(`Found existing credential: ${credential.contractId}`);
  } catch (error) {
    // 3. Create credentials request if not found
    console.log('No existing credential, creating request...');
    const request = await connection.createCredentialsRequest({
      partyId,
      providers: ['default']
    });
    console.log(`Request created: ${request.requestId}`);

    // Wait for credential to be created (in real app, use polling or webhooks)
    // For this example, we'll assume it's created
    credential = await connection.getCredentialsByPartyId(partyId);
  }

  // 4. Generate verification link
  const link = await connection.generateVerificationLink({
    contractId: credential.contractId
  });

  console.log(`\nVerification link: ${link.link}`);
  console.log(`Share this link with the user to verify their identity`);

  // 5. Get human score
  const score = await connection.getHumanScore();
  console.log(`\nCurrent human score: ${score.totalScore}/100`);

  return {
    credential,
    verificationLink: link.link,
    score: score.totalScore
  };
}

// Usage
verifyPartyIdentity('party::alice')
  .then(result => console.log('Verification setup complete:', result))
  .catch(error => console.error('Error:', error));

REST API Examples¶

Obtain Access Token¶

# Get OAuth2 access token
TOKEN_RESPONSE=$(curl -X POST https://id.devnet.cantonloop.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET")

ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')
echo "Access token: $ACCESS_TOKEN"

Create Credentials Request¶

curl -X POST https://id.devnet.cantonloop.com/api/v1/credentials-access-request \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partyId": "party::alice",
    "providers": ["provider1", "provider2"]
  }'

Get Credentials¶

# Get first page of credentials
curl -X GET "https://id.devnet.cantonloop.com/api/v1/credentials?offset=0&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Generate Verification Link¶

curl -X POST https://id.devnet.cantonloop.com/api/v1/generate-link \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "contract_123"
  }'

Check Verification Status (Public)¶

# This endpoint doesn't require authentication
curl -X GET https://id.devnet.cantonloop.com/api/v1/check/verify_token_abc123

Error Handling¶

SDK Error Handling¶

import { idSdk, IdSdkError } from '@fivenorth/id-sdk';

async function safeGetCredentials(partyId: string) {
  try {
    const connection = await idSdk.connect({
      clientId: process.env.ID_CLIENT_ID!,
      clientSecret: process.env.ID_CLIENT_SECRET!,
      network: 'devnet'
    });

    const credential = await connection.getCredentialsByPartyId(partyId);
    return credential;
  } catch (error) {
    if (error instanceof IdSdkError) {
      switch (error.code) {
        case 'NOT_FOUND':
          console.error('Credential not found');
          return null;
        case 'UNAUTHORIZED':
          console.error('Authentication failed. Check your credentials.');
          throw error;
        case 'RATE_LIMIT':
          console.error('Rate limit exceeded. Please retry later.');
          // Implement retry with exponential backoff
          throw error;
        default:
          console.error(`SDK Error: ${error.message}`);
          throw error;
      }
    } else {
      console.error('Unexpected error:', error);
      throw error;
    }
  }
}

Best Practices¶

Store Credentials Securely: Never commit client IDs and secrets to version control. Use environment variables or secret management services.
Handle Token Expiration: The SDK handles this automatically, but if using REST API, implement token refresh logic.
Implement Retry Logic: Network requests can fail. Implement retry logic with exponential backoff for transient errors.
Validate Inputs: Always validate party IDs and contract IDs before making API calls.
Use Pagination: When fetching lists, use pagination to avoid loading too much data at once.
Monitor Rate Limits: Be aware of rate limits and implement appropriate throttling.
Error Logging: Log errors appropriately for debugging while being careful not to expose sensitive information.

Next Steps¶

SDK Reference - Complete SDK method documentation
API Reference - Complete REST API documentation