HomeAPI Integration

5N ID API Integration

Seamlessly integrate 5N ID into your system and build trust from the first step.

background

Before
You Begin

Request 5N ID access

Your client account to access the API.

Get Authorized

Use your Client ID and Client Secret to obtain OAuth2 access tokens via client_credentials flow. Include the Bearer token in the Authorization header for all API requests.

Overview

5N ID allows youto integrate secure identity verification directly into your website, application, or mobile app. Our technology ensures seamless customer onboarding and Credentials compliance while serving as the unified identity layer for the Canton ecosystem

Key Features:

  • 5N ID acts as the single source of truth for user identity across the Canton network, enabling consistent and verifiable user data across applications.
  • User identity information is securely stored and managed via smart contracts, ensuring tamper-proof records and auditability.
  • Simple integration using standardized HTTP requests and responses with Authentication via secret and API keys.
  • Designed to work seamlessly with Canton’s privacy-focused blockchain infrastructure, enabling compliant data sharing between permissioned nodes.

If you have any questions or need further assistance, please don’t hesitate to contact our support team.

Guide

This guide helps you integrate your system with the 5N ID Credentials application using OAuth2 client_credentials authentication. Fast setup, secure access, and a smooth verification experience.

01

Contact Us

Fill in the application form to initiate the process. After your account is created, you'll receive an email with your login credentials and temporary password.
02

Log in to the Application

  • Go to the login page;
  • Enter your email and temporary password;
  • Change your password upon first login.
03

Access Client ID and Client Secret

You will receive a unique Client ID and Client Secret. Use them to obtain OAuth2 access tokens for authenticating your API requests with the 5N ID system.
04

Front-End Adjustments

You must update your front-end to support:
  • Triggering Credentials flow after user actions;
  • Displaying verification status to users;
  • Handling errors and responses visually.
05

Test the Integration

Use the sandbox environment to:
  • Test API authentication;
  • Simulate Credentials flows;
  • Validate all error scenarios;
  • Ensure that all functionality works end-to-end before going live.
06

Complete Integration

Once integration is tested and verified, your system will be ready to manage users and initiate Credentials processes in production.

API Overview

Use this section to understand the core technical specifications of the 5N ID API before diving into specific endpoints.

Current API Version
v1.0.0
Update Frequency
Real-time sync after every Credentials action
Base URL
https://id.devnet.cantonloop.com/api/v1
Data Formats
All requests and responses use JSON
Authentication
All requests must be authenticated using OAuth2 client_credentials flow with Bearer tokens

API Reference

API Credentials

  • Client ID
  • Institution ID
  • Client Secret

Notes

  • These credentials are provided through the institution settings page after registration.
  • Institution ID is a simple identifier for the institution.
  • It can be safely stored on the frontend, as it does not reveal any confidential information.
  • Client ID and Client Secret are used to obtain OAuth2 access tokens via the client_credentials flow.
  • Never expose your Client Secret in client-side code or commit it to version control.
  • To successfully integrate with 5N ID, users must register in both systems (5N ID + your application) and use the correct partyId for identification.

To fully integrate with the Credentials API, follow the steps below.

1. Obtain Access Token

Token EndpointPOST https://auth.console-dev.fivenorth.io/realms/5n-apps/protocol/openid-connect/token

Description

Obtain an OAuth2 access token using the client_credentials grant type. This token is required to authenticate all subsequent API requests.

Request Headers (required)

  • Content-Type – application/x-www-form-urlencoded

Request Body Parameters

  • grant_type – must be "client_credentials"
  • client_id – your Client ID
  • client_secret – your Client Secret

Token Request Example

Request an access token using client_credentials grant type:
POST https://auth.console-dev.fivenorth.io/realms/5n-apps/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Where:

client_id – your Client ID;

client_secret – your Client Secret;

grant_type – must be "client_credentials".

Response will contain an access_token:
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKUjd...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "email profile"
}

Use the access_token in the Authorization header for all subsequent API requests:

Authorization: Bearer {access_token}

Note: Access tokens expire after the time specified in expires_in (in seconds). Request a new token when needed.

cURL Example

cURL example:
curl -X POST "https://auth.console-dev.fivenorth.io/realms/5n-apps/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

Returns an access token with expiration information. Use the access_token in the Authorization header for all API requests.

2. Create Credentials Data Request

Endpoint 1POST /api/v1/institutions/credentials-access-request

Description

Creates a Credentials data request (proposal) from the institution to a user.

Request Headers (required)

  • Authorization – Bearer token obtained via OAuth2 client_credentials flow
  • Content-Type – application/json

Body Parameters

  • partyId – the party ID of the user whose credentials you are requesting (required);
  • providers – array of Credentials providers (currently available GOOGLE, LINKEDIN, GITHUB, DISCORD, TWITTER).

Authorization

OAuth2 Bearer Token (obtain via token endpoint)

Body example

const body = {
  "partyId": "party::123",
  "providers": ["GOOGLE", "LINKEDIN"]
}

cURL Example

cURL example:
curl -X POST "https://id.devnet.cantonloop.com/api/v1/api/v1/institutions/credentials-access-request" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partyId": "party::123",
    "providers": ["GOOGLE", "LINKEDIN"]
  }'

Response

Indicates that a proposal was successfully created for the user.

3. Check Credentials Request Status

Endpoint 2GET /api/v1/institutions/credentials/:partyId

Description

Retrieves the credential results disclosed by the user to the institution.

Request Headers (required)

  • Authorization – Bearer token obtained via OAuth2 client_credentials flow

Path Parameters

  • partyId – the party ID of the user whose credentials you are requesting (required).

Authorization

OAuth2 Bearer Token (same as Endpoint 1)

Example Path

/api/v1/institutions/credentials/party::123

cURL Example

cURL example:
curl -X GET "https://id.devnet.cantonloop.com/api/v1/api/v1/institutions/credentials/party::123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

Retrieves the credential results disclosed by the user to the institution. Example:
[
  {
    "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"
    }
  },
  {
    "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"
    }
  }
]

4. Generate Verification Link

Endpoint 3POST /api/v1/verification/generate-link

Description

Generates a short-lived verification link for a specific user's credential.

Request Headers (required)

  • Authorization – Bearer token obtained via OAuth2 client_credentials flow
  • Content-Type – application/json

Body Parameters

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

Authorization

OAuth2 Bearer Token (institution role required)

Body example

{
  "contractId": "008cb3c4e71260967ef"
}

cURL Example

cURL example:
curl -X POST "https://id.devnet.cantonloop.com/api/v1/api/v1/verification/generate-link" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "008cb3c4e71260967ef"
  }'

Response

Returns a verification URL and token. The URL can be shared with third parties to verify the credential status.

5. Generate Verification Links (Batch)

Endpoint 4POST /api/v1/verification/generate-links-batch

Description

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

Request Headers (required)

  • Authorization – Bearer token obtained via OAuth2 client_credentials flow
  • Content-Type – application/json

Body Parameters

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

Authorization

OAuth2 Bearer Token (institution role required)

Body example

{
  "requests": [
    {
      "contractId": "00020bf30f6b3714bff"
    },
    {
      "contractId": "008cb3c4e71260967ef"
    }
  ]
}

cURL Example

cURL example:
curl -X POST "https://id.devnet.cantonloop.com/api/v1/api/v1/verification/generate-links-batch" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "contractId": "00020bf30f6b3714bff"
      },
      {
        "contractId": "008cb3c4e71260967ef"
      }
    ]
  }'

Response

Returns an array of results. Each result contains either a verification link response or an error for failed requests. Each result includes the contractId for correlation with the original request.

6. Check Verification Status

Endpoint 5GET /api/v1/verification/check/:token

Description

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

Request Headers

  • No headers required – this is a public endpoint

Path Parameters

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

Authorization

No authentication required

cURL Example

cURL example:
curl -X GET "https://id.devnet.cantonloop.com/api/v1/api/v1/verification/check/VERIFICATION_TOKEN"

Response

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"
  }
}

Join Us in Shaping the Future of Credentials

Call for collaboration, partnerships, or community engagement.

bg