Skip to content

Organization Registration

Overview

This user story covers the process of registering a new staffing company (organization) on the REC Verifiable Credentialing Platform. The registration process integrates with the Velocity Network Registrar API to create the organization in the Velocity ecosystem.

User Stories

Basic Organization Registration

As a platform administrator,
I want to register a new staffing company on the platform,
So that they can start using the platform to issue and verify credentials.

Acceptance Criteria: - The registration form captures all required organization information: - Organization legal name - Organization trading name (if different) - Organization registration number (e.g., Companies House number) - Organization address - Organization contact details (phone, email) - Organization website - Organization industry/sector - The system validates all required fields before submission - The system integrates with the Velocity Network Registrar API to create the organization - The system stores the organization details in the platform database - The system generates a unique organization ID for the platform - The system displays appropriate error messages if registration fails - The system sends a confirmation email to the organization contact email - The system creates an audit log entry for the registration

Self-Service Organization Registration

As a staffing company representative,
I want to register my organization on the platform myself,
So that I can quickly get started with using the platform.

Acceptance Criteria: - The registration form is accessible via a public URL - The form includes all required fields as per the basic registration - The system validates the email domain against the organization website domain - The system sends a verification email to confirm the organization email - The system creates a pending organization record until verification is complete - The system notifies platform administrators of new registration requests - The system allows platform administrators to approve or reject registration requests - The system notifies the organization representative of the approval/rejection

Organization Registration API

As a system integrator,
I want to register organizations via an API,
So that I can automate the onboarding process for multiple organizations.

Acceptance Criteria: - The API accepts all required organization details - The API validates the input data before processing - The API returns appropriate success/error responses - The API requires proper authentication and authorization - The API creates the organization in both the platform and Velocity Network - The API documentation is comprehensive and includes examples

Technical Details

Velocity SDK Integration

Based on the Velocity SDK Implementation Guide, the organization registration process will migrate from direct API calls to using the Velocity SDK for improved reliability and reduced complexity.

Migration from Current API Approach

The current implementation uses: - Direct HTTP calls to Velocity Network Registrar API - Manual payload transformation (311 lines of complex code) - Custom error handling and retry logic - Limited to organization registration only

SDK Benefits

  • 68% code reduction (from 311 lines to ~100 lines estimated)
  • 37% faster development (8-10 weeks vs 12-16 weeks)
  • Built-in scalability for 1000+ concurrent users requirement
  • Automatic compliance features (GDPR, audit logs)
  • Future-proofing with automatic SDK updates

Required Environment Configuration

Essential environment variables for Velocity SDK integration: 

# Tier 1: Essential (Cannot function without these)
VNF_SDK_API_KEY=                    # SDK access key from VCL
VNF_SDK_ENVIRONMENT=sandbox         # sandbox/production
VNF_AGENT_URL=                      # Credential agent endpoint
VNF_SDK_DID=                        # Organization DID
VNF_SDK_PRIVATE_KEY=                # Signing key

# Tier 2: Core Functionality
VNF_REGISTRAR_URL=                  # Organization registration
VNF_CREDENTIAL_AGENT_URL=           # Credential operations
VNF_CREDENTIAL_ISSUER_DID=          # Issuer identity
VNF_WEBHOOK_URL=                    # Status notifications

Integration Points

  • Replace transformToVelocityPayload() with SDK methods
  • Maintain Auth0 integration alongside SDK
  • Update error handling to use SDK exceptions
  • Implement health checks for SDK connectivity

Implementation Phases

  1. Phase 1: Environment setup and SDK initialization
  2. Phase 2: Core service implementation with VelocityService
  3. Phase 3: Organization registration migration from API to SDK
  4. Phase 4: Testing and validation in sandbox environment

Database Schema

The organization entity will include the following fields: - id (UUID, primary key) - name (string, required) - trading_name (string, optional) - registration_number (string, required) - address (JSON object, required) - contact_email (string, required) - contact_phone (string, required) - website (string, required) - industry (string, required) - velocity_org_id (string, required after registration) - kyb_status (enum: PENDING, IN_PROGRESS, APPROVED, REJECTED) - created_at (timestamp) - updated_at (timestamp)

Security Considerations

  • All organization data must be encrypted at rest
  • API calls to the Velocity Network must use TLS 1.3
  • Organization registration must be logged for audit purposes
  • Access to organization data must be restricted based on user roles