Team Management API Documentation

Overview

This document provides comprehensive documentation for BlueNotary's Integrationsv2 APIs that enable vendor organizations to seamlessly manage their team members, sessions, and related resources through our platform.

This documentation currently covers Team Member management APIs and will be extended to include Session management and other integration capabilities.

Authentication
API Structure
API Endpoints
- Team Member APIs
Error Handling
Security Features
Advanced Features

Authentication

All API endpoints require vendor authentication using the vendor API key in the Authorization header:

Authorization: Bearer bnkey-{vendor_key}-{vendor_id}

Example:

Authorization: Bearer bnkey-95e0154e5f9fc6324a1674fd99515fc05ed97f07a99dd6207bd880154d0e7809-SILVDYLSJAA

API Structure

The Integrationsv2 APIs are organized into the following categories:

Available APIs

Team Members - Manage vendor team members (notaries, admins, pretaggers)
- Invite, list, retrieve
- Unlink team members
- Generate login links (frontend performs auto-verification)

API Endpoints

Team Member APIs

1. Invite Team Member

Creates a new team member (notary) for the vendor organization with automatic onboarding completion and optional seal generation.

Endpoint: POST /api/integrationsv2/team_members/invite

Request Headers

Content-Type: application/json
Authorization: Bearer {api-key}

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address of the team member
`business_role`	string	Yes	Role: `notary`, `pretagger`, `admin`
`first_name`	string	Yes	First name of the team member
`last_name`	string	Yes	Last name of the team member
`password`	string	Yes	Pre-hashed bcrypt password; if omitted, API will generate one. Use cost factor 10. Online tool.
`state`	string	Conditional	State (required if `forcefullyMarkOnboardingComplete` is enabled)
`county`	string	Conditional	County (required if `forcefullyMarkOnboardingComplete` is enabled)
`commission_number`	string	Conditional	Commission number (required if `forcefullyMarkOnboardingComplete` is enabled)
`commission_expires_on`	string	Conditional	Commission expiry date (required if `forcefullyMarkOnboardingComplete` is enabled)
`vendor_user_id`	string	No	Vendor's internal user ID for mapping
`role_options`	object	No	Role-specific permissions configuration
`optional_metadata`	object	No	Additional metadata for the user

Role Options Object

{
  "notaryCanInviteSignerForSession": "yes|no",
  "showInvoiceTabToUser": "yes|no"
}

Request Example

{
  "email": "[email protected]",
  "business_role": "notary",
  "first_name": "John",
  "last_name": "Doe",
  "state": "TX",
  "county": "Travis",
  "commission_number": "12345",
  "commission_expires_on": "2025-12-31",
  "vendor_user_id": "vendor_user_001",
  "role_options": {
    "notaryCanInviteSignerForSession": "yes",
    "showInvoiceTabToUser": "yes"
  }
}

Response

Success Response (201 Created):

{
  "success": true,
  "user_data": {
    "id": "68e92b52becca921699d153a",
    "email": "[email protected]",
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "business_role": "notary",
    "state": "TX",
    "county": "Travis",
    "commission_number": "12345",
    "commission_expires_on": "2025-12-31T00:00:00.000Z",
    "onboarding_status": "complete",
    "vendor_user_id": "vendor_user_001",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

Already Linked Response (200 OK):

{
  "success": true,
  "already_linked": true,
  "team_member_id": "68e92b52becca921699d153a"
}

Error Response (400 Bad Request):

{
  "response": "Fail",
  "response_message": "Missing mandatory fields for notary onboarding: state, county, commission_number, commission_expires_on"
}

2. List Team Members

Retrieves a paginated list of team members with optional filtering capabilities.

Endpoint: GET /api/integrationsv2/team_members

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (max: 100, default: 25)
`role`	string	No	Filter by business role
`email`	string	No	Filter by email (case-insensitive regex)

Request Example

GET /api/integrationsv2/team_members?page=1&limit=25&role=notary&email=john

Response

Success Response (200 OK):

{
  "data": [
    {
      "id": "68e92b52becca921699d153a",
      "email": "[email protected]",
      "business_role": "notary",
      "onboarding_status": "complete",
      "name": "John Doe",
      "state": "TX",
      "county": "Travis",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total_items": 50,
    "total_pages": 2
  }
}

3. Get Team Member by ID

Retrieves detailed information for a specific team member.

Endpoint: GET /api/integrationsv2/team_members/:team_member_id

Path Parameters

Parameter	Type	Required	Description
`team_member_id`	string	Yes	Unique identifier of the team member

Request Example

GET /api/integrationsv2/team_members/68e92b52becca921699d153a

Response

Success Response (200 OK):

{
  "id": "68e92b52becca921699d153a",
  "email": "[email protected]",
  "business_role": "notary",
  "onboarding_status": "complete",
  "name": "John Doe",
  "state": "TX",
  "county": "Travis",
  "created_at": "2025-01-15T10:30:00.000Z",
  "updated_at": "2025-01-15T10:30:00.000Z"
}

Error Response (404 Not Found):

{
  "response": "Fail",
  "response_message": "Team member not found"
}

4. Unlink Team Member

Removes the relationship between a team member and the vendor organization, returning the member to a free account.

Use Case: Remove team members from your vendor organization while preserving their account and data.

Endpoint: DELETE /api/integrationsv2/team_members/:team_member_id

Security: Intermediate - Soft delete, preserves user account and data. For child notary accounts, the email is modified to prevent conflicts.

Path Parameters

Parameter	Type	Required	Description
`team_member_id`	string	Yes	Unique identifier of the team member

Request Example

DELETE /api/integrationsv2/team_members/68e92b52becca921699d153a

Response

Success Response (200 OK):

{
  "success": true,
  "message": "Team member unlinked successfully"
}

What Happens on Unlink:

The UserNotaryRelation is marked as deleted (soft delete)
User's memberType is changed from pro to free
User's vendor field is set to null
Notary role options and business role fields are cleared
If the user is a child notary, their email is modified with a collision-resistant suffix (e.g., [email protected])
All vendor-related fields are cleared from the user account

Error Response (404 Not Found):

{
  "response": "Fail",
  "response_message": "Team member link not found"
}

Error Response (403 Forbidden):

{
  "response": "Fail",
  "response_message": "Vendor admin user not found"
}

Error Response (422 Validation Failed):

{
  "response": "Fail",
  "response_message": "Validation failed",
  "errors": [
    {
      "param": "team_member_id",
      "msg": "INVALID_ID"
    }
  ]
}

5. Generate Login Link

Creates a secure, temporary auto-login link with 12-hour expiry. The link uses a two-step flow where the frontend first hits an /auto/:id route to retrieve the actual login URL and then redirects the user.

Use Case: Generate an auto-login link for a team member using only their email.

When to Use: When you want to send reusable login links (valid for 12 hours) without managing nonces or JWTs.

Security: Standard - 12-hour expiry with MongoDB TTL cleanup and two-step link verification on the frontend.

Endpoint: POST /api/integrationsv2/login_links

Request Headers

POST /api/integrationsv2/login_links HTTP/1.1
Content-Type: application/json
Authorization: Bearer {vendor_key}

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address of the team member

Request Example

{
  "email": "[email protected]"
}

Response

Success Response (200 OK):

{
  "success": true,
  "login_link": "{FRONT_URL}/auto/{login_link_id}?key={login_key}",
  "expires_in": 43200
}

Two-Step Login Process:

Step 1: User clicks the login_link URL which points to /auto/{login_link_id}?key={login_key}
Step 2: Frontend automatically verifies the link and retrieves the actual login URL
Step 3: Frontend redirects user to the actual login URL which auto-submits credentials

Link Reusability: The generated link can be used multiple times within the 12-hour expiry period. It is not a one-time use link.

Security Warning: The final login URL contains credentials in query parameters. This is handled securely through the two-step verification process.

URL Encoding Note: Query parameters (especially email and password) must be URL-encoded by the client/server generating the link. Characters like %, &, +, =, and @ will break links if not encoded. Use encodeURIComponent() when building URLs.

Error Responses:

User Not Found (404 Not Found):

{
  "response": "Fail",
  "response_message": "User not found"
}

Error Handling

HTTP Status Codes

Status Code	Description
200	Success
201	Created
400	Bad Request (validation errors)
401	Unauthorized (invalid credentials/expiry)
403	Forbidden (vendor admin not found)
404	Not Found (user/team member not found)
409	Conflict (duplicate nonce)
422	Unprocessable Entity (missing required fields)
500	Internal Server Error

Error Response Format

{
  "response": "Fail",
  "response_message": "Human-readable error description",
  "internal_response": "Technical error details (development only)"
}

Security Features

1. Login Link Expiry

Purpose: Automatic link invalidation
Implementation: 12-hour expiry with automatic MongoDB TTL cleanup
Usage: Links automatically expire and are cleaned up via MongoDB TTL index

2. Two-Step Verification

Purpose: Enhanced security for login links
Implementation: Initial link points to verification endpoint, which returns actual login URL
Usage: Prevents direct credential exposure in initial link

3. Vendor Scoping

Purpose: Data isolation between vendors
Implementation: All operations scoped to vendor's team members
Usage: Vendors can only access their own data

Advanced Features

1. Automatic Onboarding Completion

When the vendor flag forcefullyMarkOnboardingComplete is enabled:

Skips manual onboarding for new team members
Makes notary fields mandatory: state, county, commission_number, commission_expires_on
Automatically generates notary seal using Python scripts
Uploads seal to S3 with public access
Updates NotaryDataModel with seal information

2. Notary Seal Generation

Process:

Validates state template exists (./public/templates/{state}.jpg)
Executes Python script (alter_seal_template.py)
Generates personalized seal with user details
Uploads to S3 with unique filename
Updates NotaryDataModel with seal URL
Cleans up temporary files

Supported States: All states with available templates

3. Comprehensive Logging

Security Note: Before logging, sensitive fields are removed/redacted to prevent credential exposure.

Vendor Logs Include:

Request metadata (IP, browser, country)
Request/response details (with sensitive fields redacted)
Error information (sanitized for user-facing, detailed for debugging)
Performance metrics
Audit trail for compliance

Credential Redaction Requirements: All sensitive fields must be removed or replaced with [REDACTED] before persistence:

password → [REDACTED]
token → [REDACTED]
api_key → [REDACTED]
client_secret → [REDACTED]
Any PII/secrets → [REDACTED]

Response Persistence Schema:

{
  "vendorLogsDoc": {
    "response_details": {
      "response": "Success|Fail",
      "response_message": "User-facing message",
      "internal_response": "Detailed error for debugging",
      "status_code": 200|400|401|403|500,
      "timestamp": "2025-01-15T10:30:00.000Z",
      "request_id": "unique_request_identifier"
    }
  }
}

Error Logging Guidelines:

User-Facing Messages: Sanitized, non-technical error messages
Debug Information: Stack traces, internal error codes, detailed failure reasons
Sensitive Data: Always redacted in both user and debug logs

4. Automatic Cleanup

Expired Login Links:

Automatically deleted via MongoDB TTL index on expiresAt field
No background jobs required
Database consistency maintained

Integration Examples

Complete Team Member Lifecycle

Environment Variables:

{API_BASE_URL}: Replace with your environment's API base URL (e.g., https://app.bluenotary.us, https://staging.bluenotary.us, http://localhost:5000)
{FRONT_URL}: Replace with your environment's frontend URL (e.g., https://app.bluenotary.us, https://staging.bluenotary.us)

# 1. Create team member
curl -X POST {API_BASE_URL}/api/integrationsv2/team_members \
  -H "Authorization: Bearer {vendor_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "business_role": "notary",
    "first_name": "John",
    "last_name": "Doe",
    "state": "TX",
    "county": "Travis",
    "commission_number": "12345",
    "commission_expires_on": "2025-12-31"
  }'

# 2. List team members
curl -X GET "{API_BASE_URL}/api/integrationsv2/team_members?page=1&limit=25" \
  -H "Authorization: Bearer {vendor_key}"

# 3. Get specific team member
curl -X GET {API_BASE_URL}/api/integrationsv2/team_members/{team_member_id} \
  -H "Authorization: Bearer {vendor_key}"

# 4. Generate login link (email-only)
curl -X POST {API_BASE_URL}/api/integrationsv2/login_links \
  -H "Authorization: Bearer {vendor_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
# 5. Unlink team member
curl -X DELETE {API_BASE_URL}/api/integrationsv2/team_members/{team_member_id} \
  -H "Authorization: Bearer {vendor_key}"

Overview

Table of Contents

Authentication

API Structure

Available APIs

API Endpoints

Team Member APIs

1. Invite Team Member

Request Headers

Request Body

Role Options Object

Request Example

Response

2. List Team Members

Query Parameters

Request Example

Response

3. Get Team Member by ID

Path Parameters

Request Example

Response

4. Unlink Team Member

Path Parameters

Request Example

Response

5. Generate Login Link

Request Headers

Request Body

Request Example

Response

Error Handling

HTTP Status Codes

Error Response Format

Security Features

1. Login Link Expiry

2. Two-Step Verification

3. Vendor Scoping

Advanced Features

1. Automatic Onboarding Completion

2. Notary Seal Generation

3. Comprehensive Logging

4. Automatic Cleanup

Integration Examples

Complete Team Member Lifecycle