Partner Service Developer Guide

This guide shows you how to implement comprehensive partner user management using the Partner service endpoints.

Quick Start

Want to get up and running fast? Follow this 5-minute setup:

Get all users → Retrieve complete user list from your partner organization
Get specific user → Fetch detailed user information
Update user → Modify user information (name, email, metadata)
Remove user → Deactivate user access (soft delete)

Prerequisites

Base URL: https://localhost:4401/partner/v1
Content-Type: application/json
Authentication: Required for all endpoints (partner API key via Bearer token)

User Management

Retrieve All Users

Purpose: Get a complete list of all users enrolled with your partner organization.

Endpoint: GET /all-users

Request:

curl -X GET https://localhost:4401/partner/v1/all-users \
  -H "Authorization: Bearer YOUR_API_KEY"

Request:

{
  "success": true,
  "data": {
    "userType": "user",
    "users": [
      {
        "userId": "550e8400-e29b-41d4-a716-446655440000",
        "name": "John Doe",
        "email": "john@example.com",
        "entityType": "user",
        "did": "did:key:z6Mk2b84e6986130ed411d0e386722b0ebb5",
        "publicKey": "base64_encoded_32_byte_public_key",
        "metadata": {
          "department": "engineering",
          "role": "developer"
        },
        "enrolledAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      {
        "userId": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "entityType": "user",
        "did": "did:key:z6Mk7b4bcd19d9dee0182ae9e9ef05c9779c",
        "publicKey": "base64_encoded_32_byte_public_key",
        "metadata": {
          "department": "marketing",
          "role": "manager"
        },
        "enrolledAt": "2024-01-15T11:00:00Z",
        "updatedAt": "2024-01-15T11:00:00Z"
      }
    ],
    "count": 2
  }
}

What you get:

Complete user list with enrollment details
Cryptographic identifiers (DID, public key)
Custom metadata from enrollment
Timestamps for audit purposes
Only active (non-deactivated) users

Get Specific User

Purpose: Retrieve detailed information about a specific user by their ID.

Endpoint: POST /get-user

Request

curl -X POST https://localhost:4401/partner/v1/get-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "success": true,
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john@example.com",
    "entityType": "user",
    "did": "did:key:z6Mk2b84e6986130ed411d0e386722b0ebb5",
    "publicKey": "base64_encoded_32_byte_public_key",
    "metadata": {
      "department": "engineering",
      "role": "developer",
      "permissions": ["read", "write"]
    },
    "enrolledAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Use cases:

User profile display
Permission checking
Audit trail verification
Integration with other services

Update User

Purpose: Modify a user's information (name, email, metadata) in the system.

Endpoint: PATCH /update-user

Request

curl -X PATCH https://localhost:4401/partner/v1/update-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Smith",
    "email": "john.smith@example.com",
    "state": "active",
    "metadata": {
      "department": "engineering",
      "role": "senior_developer"
    }
  }'

Response

{
  "success": true,
  "message": "User 550e8400-e29b-41d4-a716-446655440000 has been successfully updated.",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "partnerId": "your-partner-id",
    "enrollmentId": "enrollment-789",
    "updatedFields": ["name", "email", "metadata"],
    "updatedAt": "2024-01-15T12:00:00Z",
    "enrollment": {
      "id": "enrollment-789",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "metadata": {
        "department": "engineering",
        "role": "senior_developer",
        "state": "active"
      },
      "updatedAt": "2024-01-15T12:00:00Z"
    }
  }
}

Available update fields:

name - User's display name
email - User's email address
state - User state (stored in metadata)
metadata - Custom metadata object

Note: The state field is automatically stored in the metadata object for enhanced flexibility.

Remove User

Purpose: Deactivate a user's access (soft delete) in the system.

Endpoint: DELETE /remove-user

Request

curl -X DELETE https://localhost:4401/partner/v1/remove-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

{
  "success": true,
  "message": "User 550e8400-e29b-41d4-a716-446655440000 has been successfully removed from enrollments.",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "partnerId": "your-partner-id",
    "enrollmentId": "enrollment-789",
    "deactivatedAt": "2024-01-15T12:30:00Z",
    "status": "deactivated"
  }
}

What happens:

User access is marked as deactivated (soft delete)
User data is preserved for audit purposes
User will no longer appear in active user lists
Cannot be updated after deactivation

Complete Working Example

Here's a complete user management flow you can copy-paste and run:

1. Get All Users

curl -X GET https://localhost:4401/partner/v1/all-users \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Get Specific User

curl -X POST https://localhost:4401/partner/v1/get-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

3. Update User

curl -X PATCH https://localhost:4401/partner/v1/update-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Smith",
    "email": "john.smith@example.com",
    "state": "active"
  }'

4. Remove User

curl -X DELETE https://localhost:4401/partner/v1/remove-user \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Common Errors & Solutions

401 Unauthorized

Problem: Invalid or missing Bearer token

Solution: Ensure your API key is valid and included in Authorization header

400 Bad Request

Problem: Invalid request format, missing fields, or trying to update deactivated user

Solution: Check JSON syntax, ensure all required fields are present, verify user is active

403 Forbidden

Problem: Missing partnerId from authentication context

Solution: Ensure proper authentication and partner ID is available

404 Not Found

Problem: User not found in enrollments

Solution: Verify the user ID exists and is enrolled with your partner

500 Internal Server Error

Problem: Database connection or system error

Solution: Check service logs and ensure the system is accessible

That's it! You now have a comprehensive partner user management system. The service handles all the complexity of user data management, authentication, and system integration - you just make HTTPs requests and get powerful user management capabilities!

← Back to Tutorials