Build Custom Userinfo (Resource) API

Overview

Login 3.0 allows companies to build custom user information retrieval and synchronization systems through configurable endpoints. These endpoints are designed to retrieve and update user data in the company’s database after successful authentication.

Required API Endpoints

Method	Endpoint	Description
GET	/userinfo	Retrieve user information from the service database
POST	/userinfo	Create or update user information in the service database (UPSERT)
DELETE	/userinfo	Delete user information from the service database
GET	/user_existing_info	Retrieve user information from the alignment database, if exists

Userinfo Endpoint

Purpose

The userinfo endpoint is used to retrieve additional user attributes or information from the company's database following successful authentication via Login 3.0. It enables client applications to request specific user details that are not included in the initial authentication payload.

Endpoint URL:

GET /userinfo

Implementation

1. Endpoint Setup: Companies should create an endpoint on their server to handle requests for additional user information after authentication through Login 3.0.

2. Access Token Usage: When a user successfully authenticates, an access token is provided. This token should be included in the request header (Authorization: Bearer {ACCESS_TOKEN}) to access additional user details.

3. Response Format: The endpoint should return the requested user details in a structured format such as JSON. This allows the client application to consume and process the data efficiently.

Example Request:

GET https://{yourCompanyDomain}/userinfo
Authorization: Bearer {ACCESS_TOKEN}

Example Response:

{
  "sub": "did:key:123456789abcdefghi",
  "email": "[e-mail]",
  "email_verified": true,
  "name": "Jane Josephine Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "middle_name": "Josephine",
  "nickname": "JJ",
  "username": "janedoe",
  "phone_number": "[phone]",
  "phone_number_verified": false,
  "gender": "female",
  "birthdate": "1972-03-31",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "postal_code": "10001",
    "country": "US"
  },
  "created_at": "2023-10-21T14:23:45Z",
  "updated_at": "2023-10-22T10:10:00Z"
}

Example Errors:

Errors

---

User Existing Info Endpoint

Purpose

The user_existing_info endpoint is used to retrieve and synchronize user data from the company’s CRM or database with the latest information obtained during the authentication process. This ensures that the system always reflects the most accurate user details.

Endpoint URL:

GET /user_existing_info

Implementation

1. Endpoint Setup: Similar to the userinfo endpoint, companies should establish an endpoint to handle requests for existing user data.

2. Data Comparison: When a user logs in, the system compares their authenticated information with what is stored in the company's CRM or database. If discrepancies are found, the system can trigger a data synchronization process.

3. Response Format: The endpoint should return either the existing user data (if found) or an appropriate status indicating no record exists.

Example Request:

GET https://{yourCompanyDomain}/user_existing_info
Authorization: Bearer {ACCESS_TOKEN}

Example Response:

{
  "user_id": "12345",
  "name": "John Doe",
  "email": "[e-mail]",
  "status": "active",
  "last_login": "2023-10-21T14:23:45Z"
}

---

UPSERT Userinfo Endpoint

Purpose

The UPSERT userinfo endpoint is designed to update or insert (upsert) user information into the company’s CRM or database following successful authentication. This is ideal for keeping user records up to date with minimal manual intervention.

Endpoint URL:

POST /userinfo

Implementation

1. Endpoint Setup: Companies should create an endpoint to handle UPSERT requests. This ensures that new user information is created if it doesn’t already exist, or updated if the user is already present.

2. Access Token Usage: After successful authentication, the access token is used to authorize the UPSERT request.

3. Data Synchronization: This endpoint allows client applications to synchronize user details between the client and company’s CRM in real-time.

Example Request:

POST https://{yourCompanyDomain}/userinfo
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "sub": "did:key:123456789abcdefghi",
  "name": "John Doe",
  "email": "[e-mail]",
  "phone_number": "[phone]",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "postal_code": "10001"
  }
}

Example Response:

TBD

---

DELETE Userinfo Endpoint

Purpose

The DELETE userinfo endpoint is used to remove a user's information from the company's database after successful authentication via Login 3.0. It enables client applications to request the deletion of specific user details stored on the server.

Endpoint URL:

DELETE /userinfo

Implementation

• Endpoint Setup: Companies should create a DELETE endpoint on their server to handle requests for removing user information after authentication through Login 3.0.

• Access Token Usage: When a user successfully authenticates, an access token is provided. This token should be included in the request header (Authorization: Bearer {ACCESS_TOKEN}) to authorize the deletion of the user’s details.

• Response Format: The endpoint should return a confirmation message in a structured format, such as JSON, to indicate that the user’s information has been successfully deleted.

Example Request:

DELETE https://{yourCompanyDomain}/userinfo
Authorization: Bearer {ACCESS_TOKEN}

Example Response:

TBD

Example Errors:

Database and API Response Schema Guidelines

Database Guidelines:

1. User Information: Store key attributes such as sub, name, email, phone_number, address, and timestamps (created_at, updated_at).

2. Versioning: Keep track of user information changes by maintaining version control, or adding audit tables to record historical data.

3. Indexes: Ensure your user database has indexes on frequently queried fields like sub and email for better performance.

4. Data Normalization: Use normalized tables for related data (e.g., user’s address) to minimize redundancy and maintain data integrity.

CREATE TABLE `users` (
    `sub` VARCHAR(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT 'User DID',
    `wallet_address` VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User wallet address (EOA)',
    `email` VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User email',
    `email_verified` BOOLEAN NOT NULL DEFAULT 0 COMMENT 'Email verification status',
    `name` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User full name',
    `first_name` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User first name',
    `last_name` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User last name',
    `middle_name` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User middle name',
    `nickname` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User nickname',
    `username` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'Preferred username',
    `first_name_katakana` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User first name in Katakana',
    `last_name_katakana` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User last name in Katakana',
    `middle_name_katakana` VARCHAR(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User middle name in Katakana',    
    `phone_number` VARCHAR(31) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User phone number',
    `phone_number_verified` BOOLEAN NOT NULL DEFAULT 0 COMMENT 'Phone number verification status',
    `profile` VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'Profile URL',
    `picture` VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'Profile picture URL',
    `website` VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'Website URL',
    `gender` ENUM('male', 'female', 'genderless') CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User gender',
    `birthdate` VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT 'User birthdate',
    `address` JSON DEFAULT NULL COMMENT 'User address in JSON format (street, city, postal_code, country)',
    `identities` JSON DEFAULT NULL COMMENT 'User identities in JSON format (e.g., external auth providers)',
    `privacy_policy_agreement_date` DATETIME DEFAULT NULL COMMENT 'Date of privacy policy agreement',
    `privacy_policy_agreement` BOOLEAN NOT NULL DEFAULT FALSE COMMENT 'Privacy policy agreement status',
    `created_at` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) COMMENT 'User record creation date',
    `updated_at` TIMESTAMP(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6) COMMENT 'User record last update date',
    UNIQUE INDEX `IDX_email` (`email`),
    UNIQUE INDEX `IDX_sub` (`sub`),
    UNIQUE INDEX `IDX_wallet_address` (`wallet_address`),
    PRIMARY KEY (`sub`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Addresss

{
    "street": "123 Main St",
    "city": "New York",
    "postal_code": "10001",
    "country": "US"
}

Identities

[
  {
    "provider": "google",
    "user_id": "1234567890",
    "connection": "google",
    "isSocial": true
  },
  {
    "provider": "otp",
    "user_id": "[e-mail]",
    "connection": "otp",
    "isSocial": false
  }
]

Gender - male female genderless

https://learn.microsoft.com/en-us/java/api/com.microsoft.azure.cognitiveservices.vision.faceapi.models.gender?view=azure-java-stable

Table definition

Here is a table format of the SQL schema, presented in a way that a non-developer can easily understand:

Field Name	Type	Description	Additional Info
sub	String (100)	Unique identifier for the user (User DID)	Must be unique (Primary Key)
email	String (255)	User's email address	Must be unique
email_verified	Boolean	Status indicating if the user's email is verified	Default is "No" (0)
name	String (50)	User's full name
first_name	String (50)	User's first name
last_name	String (50)	User's last name
middle_name	String (50)	User's middle name
nickname	String (50)	User's nickname
username	String (50)	Preferred username for the user
first_name_katakana	String (50)	User's first name in Katakana (Japanese)
last_name_katakana	String (50)	User's last name in Katakana (Japanese)
middle_name_katakana	ring (50)	User's middle name in Katakana (Japanese)
phone_number	String (31)	User's phone number
phone_number_verified	Boolean	Status indicating if the user's phone number is verified	Default is "No" (0)
profile	String (255)	URL to the user's profile
picture	String (255)	URL to the user's profile picture
website	String (255)	URL to the user's personal website
gender	String (8)	User's gender
birthdate	Date	User's date of birth
address	JSON	User's address in JSON format (street, city, postal code, country)
identities	JSON	User's identities in JSON format (e.g., external authentication providers like Google, Facebook)
created_at	Timestamp	Date and time the user record was created	Automatically set to the current timestamp when the record is created
updated_at	Timestamp	Date and time the user record was last updated	Automatically updates when the record is modified
Indexes
IDX_sub	Unique Index	Ensures that the sub field is unique
IDX_email	Unique Index	Ensures that the email field is unique
IDX_wallet_address	Unique Index	Ensures that the wallet_address field is unique

Example Response Errors 4xx 5xx

Errors