5N ID Integration

Description

Create and authenticate a connection to the 5N ID service. The SDK automatically handles OAuth2 token management, including token acquisition, caching, and refresh.

Parameters

• clientId – your Client ID (required)
• clientSecret – your Client Secret (required)
• network – network environment: "devnet" or "mainnet" (optional, defaults to "mainnet")

Network Configuration

The SDK supports two networks: mainnet (production, default) and devnet (development). URLs are automatically resolved based on the network.

Example

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

// Connect to mainnet (default)
const connection = await idSdk.connect({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

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

// Connect to devnet
const devConnection = await idSdk.connect({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  network: 'devnet',
});

Description

Retrieve users (institution users / KYC data requests) with optional pagination and filters. Maps to GET /institutions/me/users.

Parameters (optional)

• offset – number of records to skip (default: 0)
• limit – maximum number of records to return
• orderBy, orderType, status, reqStatus, kycStatus, search – optional filters

Example

const result = await connection.getUsers({ offset: 0, limit: 20 });

console.log(result.items);       // Institution users / KYC data requests
console.log(result.pagination);  // { offset, limit, total }
// Optional filters: orderBy, orderType, status, reqStatus, kycStatus, search
const filtered = await connection.getUsers({
  offset: 0,
  limit: 10,
  status: 'ACTIVE',
  search: 'user@example.com',
});

Response

Returns a UsersListResponse: { items: InstitutionUser[], pagination, totalCount? }.

Description

Retrieve human scores with pagination or filtered by party IDs. Maps to GET /institutions/me/human-scores. Use getHumanScoreByPartyId(partyId) for a single party.

Parameters (optional)

• offset, limit – pagination (when not using partyIds)
• partyIds – array of party IDs to get human scores for

Example

// By party IDs
const result = await connection.getHumanScores({
  partyIds: ['party::user1', 'party::user2'],
});
for (const item of result.items) {
  console.log(item.partyId, 'Score:', item.humanScore.totalScore);
}

// Paginated (all approved users)
const page = await connection.getHumanScores({ offset: 0, limit: 10 });
console.log(page.items, page.pagination);

Response

Returns HumanScoresListResponse: { items: { partyId, humanScore }[], pagination }.

Note

Calls GET /institutions/me/human-scores. For single party use getHumanScoreByPartyId(partyId).

Description

Retrieve the human score for a single party. Maps to GET /institutions/me/human-scores/:partyId.

Parameters

• partyId – the party ID (required)

Example

const item = await connection.getHumanScoreByPartyId('party::user1');

console.log(item.partyId);
console.log(item.humanScore.totalScore);
console.log(item.humanScore.badges);
console.log(item.humanScore.breakdown);

Response

Returns HumanScoreItem: { partyId, humanScore } (totalScore, confidenceLevel, breakdown, badges, details).

Response Example

{
  "totalScore": 91,
  "confidenceLevel": "high",
  "breakdown": {
    "accountAgeScore": 35,
    "socialMetricsScore": 16,
    "emailConsistencyScore": 20,
    "providerCountScore": 20
  },
  "badges": [
    {
      "id": "account-age-veteran",
      "name": "Veteran",
      "description": "Verified account older than 10 years",
      "level": "platinum",
      "category": "Account Age"
    },
    {
      "id": "email-perfect",
      "name": "Perfect",
      "description": "Same email across all providers",
      "level": "platinum",
      "category": "Email Consistency"
    },
    {
      "id": "provider-all-star",
      "name": "All-Star",
      "description": "Connected 5+ verification providers",
      "level": "platinum",
      "category": "Provider Count"
    },
    {
      "id": "verified-status-verified",
      "name": "Verified",
      "description": "Has at least one verified account",
      "level": "gold",
      "category": "Verified Status"
    },
    {
      "id": "developer-beginner",
      "name": "Beginner",
      "description": "1+ public repositories",
      "level": "bronze",
      "category": "Developer Activity"
    }
  ],
  "details": {
    "accountAges": [
      {
        "provider": "GITHUB",
        "ageInDays": 4129
      },
      {
        "provider": "DISCORD",
        "ageInDays": 99
      },
      {
        "provider": "TWITTER",
        "ageInDays": 82
      }
    ],
    "socialMetrics": [
      {
        "provider": "GITHUB",
        "ageInDays": 4129,
        "email": "user@example.com",
        "accountCreatedAt": "2014-09-27T08:47:46.000Z",
        "githubRepos": 1,
        "githubFollowers": 6,
        "followingCount": 5
      },
      {
        "provider": "DISCORD",
        "ageInDays": 99,
        "email": "user@example.com",
        "accountCreatedAt": "2025-10-09T08:13:32.713Z",
        "verified": true
      },
      {
        "provider": "TWITTER",
        "ageInDays": 82,
        "email": "@username",
        "accountCreatedAt": "2025-10-25T18:11:26.000Z",
        "followersCount": 8,
        "followingCount": 1,
        "postsCount": 0,
        "verified": false
      }
    ],
    "emailConsistency": {
      "uniqueEmails": [
        "user@example.com"
      ],
      "consistencyScore": 20
    },
    "providerCount": 5,
    "allUserInfo": [],
    "allTokenClaims": []
  }
}

Description

Retrieve all approved credentials that your institution has access to, with pagination and/or filter by party IDs. Returns credentials with freshness status and metadata. Maps to GET /institutions/me/credentials.

Parameters (optional)

• offset – number of records to skip (default: 0)
• limit – maximum number of records to return (default: 10)
• partyIds – array of party IDs to filter by (optional)

Example

// Get first page (default: offset=0, limit=10)
const allCredentials = await connection.getCredentials();

console.log(allCredentials.items); // Array of credentials
console.log(allCredentials.pagination); // { offset, limit, total }

// With pagination
const page2 = await connection.getCredentials({
  offset: 10,
  limit: 20,
});

Response

Returns a CredentialsListResponse object containing an array of credentials and pagination information.

Response Example

{
  "items": [
    {
      "partyId": "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
      "contractId": "008064f25bcfa1dff5129a3e5cbf68553cf48400dda996bfd58b5c21c5bca454ecca11122025436ea2b81f3558afe832a943f9b92a864104cc8d53f3f9fc6ae4e48b119e7a",
      "provider": "GOOGLE",
      "kycStatus": "APPROVED",
      "expirationDate": "2024-12-31T23:59:59.000Z",
      "issuedAt": "2024-01-01T00:00:00.000Z",
      "freshness": "FRESH",
      "metadata": {
        "email": "user@example.com",
        "firstName": "John",
        "lastName": "Doe"
      }
    },
    {
      "partyId": "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
      "contractId": "00b16e63ea75e5ace293f7bd0df8af9dea49e021883387a3120871617eb9e8fbf5ca111220e702bde51f70c5c1915dab37c288e617786296506ef8eb201ef54693f7323395",
      "provider": "LINKEDIN",
      "kycStatus": "APPROVED",
      "expirationDate": "2024-12-31T23:59:59.000Z",
      "issuedAt": "2024-01-05T00:00:00.000Z",
      "freshness": "MODERATE",
      "metadata": {
        "email": "user@example.com",
        "firstName": "Jane",
        "lastName": "Smith"
      }
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 25
  }
}

Note

For additional details including request headers, query parameters, and cURL examples, see the corresponding endpoint in the API Reference section.

Description

Get credentials disclosed by a specific user to your institution. Returns an array of all credentials for the specified party ID. Maps to GET /institutions/me/credentials/:partyId.

Parameters

• partyId – the party ID of the user (required)

Example

const userCredentials = await connection.getCredentialsByPartyId('party::123');

userCredentials.forEach(credential => {
  console.log(credential.provider); // 'GOOGLE', 'LINKEDIN', etc.
  console.log(credential.kycStatus); // 'APPROVED', 'REJECTED', etc.
  console.log(credential.metadata.email); // User's email
  console.log(credential.freshness); // 'FRESH', 'MODERATE', 'STALE', 'REVOKED'
});

Response

Returns an array of Credential objects, each containing provider, kycStatus, metadata, freshness status, and other credential information.

Response Example

[
  {
    "partyId": "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
    "provider": "GOOGLE",
    "kycStatus": "APPROVED",
    "expirationDate": "2026-11-06T08:05:34.576Z",
    "contractId": "04a5835d6cc470817989e9acc1f20c0a::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
    "metadata": {
      "email": "user@example.com",
      "lastName": "Doe",
      "firstName": "John",
      "providerId": "114130885620656351623",
      "verifiedAt": "2025-11-06T08:05:27.056Z",
      "emailVerified": true,
      "profilePicture": "https://lh3.googleusercontent.com/a/xxx"
    }
  },
  {
    "partyId": "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
    "provider": "GITHUB",
    "kycStatus": "APPROVED",
    "expirationDate": "2026-11-06T08:05:51.597Z",
    "contractId": "04a5835d6cc470817989e9acc1f20c0a::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb1",
    "metadata": {
      "email": "user@example.com",
      "lastName": "Doe",
      "username": "johndoe",
      "firstName": "John",
      "providerId": "8937226",
      "verifiedAt": "2025-11-06T08:05:44.262Z",
      "profilePicture": "https://avatars.githubusercontent.com/u/xxxx?v=4"
    }
  }
]

Note

For additional details including request headers, path parameters, and cURL examples, see the corresponding endpoint in the API Reference section.

Description

Institution-only. Resolve credentials using a single method. The behavior depends on the options provided: use `q` (email/username/domain) for forward lookup, `partyId` for reverse lookup, or `a` for alias lookup (purchased alias/FQDN). This is a unified method that automatically determines the lookup based on provided options.

Parameters

• options – ResolveCredentialsOptions object containing either:
• - q – email address, username, or domain for forward lookup (case-insensitive)
• - partyId – party ID for reverse lookup (e.g., "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0")
• - a – purchased alias/FQDN for alias lookup (e.g., "alice.5n.xyz")
• Note: Provide exactly one of q, partyId, or a.

Example

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

const connection = await idSdk.connect({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  network: 'mainnet' // or 'devnet'
});

// Forward lookup: Find credentials by email or username
const result1 = await connection.resolveCredentials({
  q: 'user@example.com'
});

console.log('Found credentials:', result1.credentials);
console.log('Party ID:', result1.credentials[0]?.partyId);

// Reverse lookup: Find all credentials by party ID
const result2 = await connection.resolveCredentials({
  partyId: 'party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0'
});

console.log('All credentials for this party:', result2.credentials);

// Alias lookup: Resolve by purchased alias/FQDN
const result3 = await connection.resolveCredentials({
  a: 'alice.5n.xyz'
});

console.log('Credentials resolved by alias:', result3.credentials);

Response

Returns a ResolveCredentialsResponse object containing an array of credentials. Each credential includes partyId, userId, email, username, kycProvider, contractId, and metadata.

Response Example

{
  "credentials": [
    {
      "partyId": "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
      "userId": 123,
      "email": "user@example.com",
      "username": "johndoe",
      "firstName": "John",
      "lastName": "Doe",
      "kycProvider": "GOOGLE",
      "contractId": "contract::123",
      "metadata": {
        "emailVerified": true,
        "profilePicture": "https://example.com/avatar.jpg"
      }
    },
    {
      "partyId": "party::12200d35764b9b490251e499af00626b54516c4f3f1c021c2eb72bf7c72f38662cb0",
      "userId": 123,
      "email": "user@example.com",
      "username": "johndoe",
      "kycProvider": "GITHUB",
      "contractId": "contract::456",
      "metadata": {
        "githubFollowers": 150,
        "githubRepos": 25
      }
    }
  ]
}

Usage Notes

• Forward lookup (q option): Search is case-insensitive and matches against both email and username fields
• Reverse lookup (partyId option): Returns all credentials associated with the party ID across all providers
• Alias lookup (a option): Resolves alias/FQDN to party ID first, then returns credentials for that party
• Only returns credentials that the institution has approved access to
• Returns empty array if no matches found
• Can return multiple credentials if user has multiple providers
• Throws an error if more than one lookup parameter is provided, or if none is provided

Note

Calls GET /institutions/me/credentials/resolve. The SDK also provides convenience methods resolve(query), reverseResolve(partyId), and resolveByAlias(alias). For additional details see the API Reference section.

Description

Request credentials from a user by creating a credentials access request (proposal). This sends a request to the user to share their credentials. Maps to POST /institutions/me/credentials/request.

Parameters

• partyId – the party ID of the user whose credentials you are requesting (required)
• providers – array of credential providers: ["GOOGLE", "LINKEDIN", "GITHUB", "GITLAB", "DISCORD", "TWITTER", "TWITCH", "REDDIT"] (required)

Example

await connection.createCredentialsRequest({
  partyId: 'party::123',
  providers: ['GOOGLE', 'LINKEDIN', 'GITHUB'],
});

Response

Returns void on success. Indicates that a proposal was successfully created for the user.

Description

Generate a short-lived verification link for a specific credential. The link can be shared with third parties to verify the credential status.

Parameters

• contractId – the contract ID of the specific credential (required)

Example

const verification = await connection.generateVerificationLink({
  contractId: '008cb3c4e71260967ef...',
});

console.log(verification.verificationUrl); // URL to share
console.log(verification.token); // Token for status checking

Response

Returns a GenerateVerificationLinkResponse object containing verificationUrl and token.

Description

Generate verification links for multiple credentials in a single request. Useful for bulk verification operations. Maximum 100 requests per batch. Each item is processed independently - partial failures are returned in the response.

Parameters

• requests – array of verification link requests (required, max 100 items)
• Each request object contains:
• - contractId – the contract ID (required)

Example

const batchResult = await connection.generateVerificationLinksBatch({
  requests: [
    { contractId: '00020bf30f6b3714bff...' },
    { contractId: '008cb3c4e71260967ef...' },
  ],
});

batchResult.results.forEach(result => {
  if (result.result) {
    console.log(`Success: ${result.result.verificationUrl}`);
  } else if (result.error) {
    console.error(`Error: ${result.error.message}`);
  }
});

Response

Returns a BatchGenerateVerificationLinkResponse object containing an array of results. Each result contains either a verification link response or an error for failed requests.

Description

Check the verification status for a verification token. This is a public endpoint (no authentication required) and is typically used by third parties who received a verification link.

Parameters

• token – the verification token from the verification URL (required)

Example

const status = await connection.checkVerificationStatus('verification-token');

console.log(status.status); // 'strong', 'moderate', 'weak', etc.
console.log(status.color); // 'green', 'amber', 'red'
console.log(status.isActive); // boolean
console.log(status.credentialData); // Original credential metadata

Response

Returns a VerificationStatusResponse object containing status, color, isActive flags, credential data, and other verification information.

Response Example

{
  "status": "strong",
  "color": "green",
  "contractId": "008cb3c4e71260967ef",
  "issuedAt": "2025-01-15T10:30:00Z",
  "expiredAt": "2025-02-15T10:30:00Z",
  "isActive": true,
  "isArchived": false,
  "isSuperseded": false,
  "isRevoked": false,
  "message": "Credentials verified successfully",
  "kycProvider": "GOOGLE",
  "credentialData": {
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Note

For additional details including path parameters and cURL examples, see the corresponding endpoint in the API Reference section.