Confidential Opportunities API

Overview

The Confidential Opportunities API provides exclusive access to premium, high-value opportunities within the Ring Platform. This endpoint is restricted to users with CONFIDENTIAL or ADMIN roles and implements advanced security measures to protect sensitive business information.

Endpoint Details

• URL: /api/confidential/opportunities
• Method: GET
• Authentication: Required (JWT Token)
• Authorization: CONFIDENTIAL or ADMIN role required
• Rate Limit: 60 requests per minute
• Caching: Disabled (force-dynamic)

Ring Platform Confidential System

What Makes Opportunities Confidential?

Ring Platform's Confidential Opportunities represent the premium tier of professional networking:

Exclusive Access Model

• High-Value Positions: C-level, VP, and senior technical roles
• Sensitive Projects: Stealth startups, M&A activities, strategic initiatives
• Premium Partnerships: Exclusive business collaborations and joint ventures
• Confidential Deals: Non-public investment opportunities and acquisitions

Security & Privacy Features

• Role-Based Access: Only CONFIDENTIAL and ADMIN users can access
• No Caching: Fresh data on every request to prevent information leakage
• Audit Logging: All access attempts are logged for security monitoring
• Enhanced Encryption: Additional security layers for sensitive data

Business Value Proposition

• Executive Recruitment: Access to top-tier talent and positions
• Strategic Partnerships: Exclusive business development opportunities
• Investment Opportunities: Private equity and venture capital deals
• Industry Intelligence: Market insights and competitive intelligence

Confidential vs. Public Opportunities

Feature	Public Opportunities	Confidential Opportunities
Access Level	All authenticated users	CONFIDENTIAL/ADMIN only
Content Type	Standard job postings	Executive roles, strategic deals
Visibility	Searchable, indexed	Hidden from general search
Security	Standard encryption	Enhanced security measures
Audit Trail	Basic logging	Comprehensive audit logging
Caching	Cached for performance	No caching for security

Authentication & Authorization

Required Roles

• CONFIDENTIAL: Premium access tier for verified professionals
• ADMIN: Full platform administration access

Role Hierarchy

VISITOR → SUBSCRIBER → MEMBER → CONFIDENTIAL → ADMIN
                                      ↑
                              Required minimum level

Authorization Check

function hasConfidentialAccess(userRole: string): boolean {
  return ['confidential', 'admin'].includes(userRole.toLowerCase());
}

Query Parameters

Parameter	Type	Description	Default	Example
page	number	Page number for pagination	1	?page=2
limit	number	Items per page (max 50)	20	?limit=10
sort	string	Sort field and direction	createdAt:desc	?sort=budget:desc
filter	string	Search filter string	-	?filter=blockchain
startAfter	string	Cursor for pagination	-	?startAfter=doc_id

Sort Options

• createdAt:desc - Newest first (default)
• createdAt:asc - Oldest first
• budget:desc - Highest budget first
• budget:asc - Lowest budget first
• title:asc - Alphabetical by title
• expirationDate:asc - Expiring soon first

Request Format

Headers

GET /api/confidential/opportunities?page=1&limit=20&sort=budget:desc
Authorization: Bearer <jwt_token>

Example Requests

# Get first page of confidential opportunities
GET /api/confidential/opportunities

# Search for blockchain opportunities
GET /api/confidential/opportunities?filter=blockchain&limit=10

# Get high-budget opportunities
GET /api/confidential/opportunities?sort=budget:desc&limit=5

# Paginate with cursor
GET /api/confidential/opportunities?startAfter=opp_123456789&limit=20

Response Format

Success Response (200 OK)

{
  "opportunities": [
    {
      "id": "conf_opp_123456789",
      "type": "offer",
      "title": "Chief Technology Officer - Stealth AI Startup",
      "isConfidential": true,
      "briefDescription": "Lead technology strategy for a well-funded AI startup in stealth mode",
      "fullDescription": "We are seeking an exceptional CTO to join our founding team and lead the development of revolutionary AI technology. This is a unique opportunity to shape the future of artificial intelligence while working with world-class investors and advisors.",
      "createdBy": "user_987654321",
      "organizationId": "entity_stealth_startup",
      "dateCreated": "2025-01-14T10:00:00Z",
      "dateUpdated": "2025-01-14T15:30:00Z",
      "expirationDate": "2025-02-28T23:59:59Z",
      "status": "active",
      "category": "Executive Leadership",
      "tags": ["cto", "ai", "startup", "founding-team", "stealth"],
      "location": "San Francisco, CA / Remote",
      "budget": {
        "min": 300000,
        "max": 500000,
        "currency": "USD",
        "equity": "2-5%",
        "additional": "Significant equity upside potential"
      },
      "requiredSkills": [
        "AI/ML leadership experience",
        "Startup CTO experience",
        "Team building and scaling",
        "Product strategy",
        "Fundraising experience"
      ],
      "requiredDocuments": [
        "Executive resume",
        "Leadership portfolio",
        "References from previous roles",
        "NDA required"
      ],
      "attachments": [
        {
          "url": "https://secure.ring.ck.ua/confidential/role-overview.pdf",
          "name": "Executive Role Overview (Confidential).pdf"
        }
      ],
      "visibility": "confidential",
      "contactInfo": {
        "linkedEntity": "entity_stealth_startup",
        "contactAccount": "user_987654321",
        "confidentialContact": true
      },
      "confidentialDetails": {
        "fundingStage": "Series A",
        "investors": ["Top Tier VC", "Strategic Angels"],
        "valuation": "Confidential",
        "teamSize": "15-20 engineers",
        "runway": "24+ months"
      }
    }
  ],
  "totalPages": 5,
  "totalOpportunities": 87,
  "lastVisible": "conf_opp_123456789",
  "pagination": {
    "currentPage": 1,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Permission Denied

{
  "error": "Permission denied"
}

404 Resource Not Found

{
  "error": "Resource not found"
}

500 Internal Server Error

{
  "error": "Internal Server Error"
}

Code Examples

JavaScript/TypeScript

interface ConfidentialOpportunity {
  id: string;
  type: 'offer' | 'request';
  title: string;
  isConfidential: true;
  briefDescription: string;
  fullDescription?: string;
  createdBy: string;
  organizationId: string;
  dateCreated: string;
  dateUpdated: string;
  expirationDate: string;
  status: 'active' | 'closed' | 'expired';
  category: string;
  tags: string[];
  location: string;
  budget?: {
    min: number;
    max: number;
    currency: string;
    equity?: string;
    additional?: string;
  };
  requiredSkills: string[];
  requiredDocuments: string[];
  attachments: Array<{
    url: string;
    name: string;
  }>;
  visibility: 'confidential';
  contactInfo: {
    linkedEntity: string;
    contactAccount: string;
    confidentialContact: boolean;
  };
  confidentialDetails?: {
    fundingStage?: string;
    investors?: string[];
    valuation?: string;
    teamSize?: string;
    runway?: string;
  };
}

interface ConfidentialOpportunitiesResponse {
  opportunities: ConfidentialOpportunity[];
  totalPages: number;
  totalOpportunities: number;
  lastVisible: string | null;
  pagination: {
    currentPage: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
}

async function getConfidentialOpportunities(params: {
  page?: number;
  limit?: number;
  sort?: string;
  filter?: string;
  startAfter?: string;
} = {}): Promise<ConfidentialOpportunitiesResponse> {
  const searchParams = new URLSearchParams();
  
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined) {
      searchParams.append(key, String(value));
    }
  });

  const response = await fetch(`/api/confidential/opportunities?${searchParams.toString()}`, {
    headers: {
      'Authorization': `Bearer ${getConfidentialToken()}`
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Failed to fetch confidential opportunities');
  }

  return response.json();
}

// Usage examples
try {
  // Get high-value opportunities
  const highValue = await getConfidentialOpportunities({
    sort: 'budget:desc',
    limit: 10
  });
  
  // Search for executive roles
  const executiveRoles = await getConfidentialOpportunities({
    filter: 'cto ceo vp executive',
    page: 1
  });
  
  // Get AI/ML opportunities
  const aiOpportunities = await getConfidentialOpportunities({
    filter: 'ai machine learning',
    sort: 'createdAt:desc'
  });
  
  console.log('Found', highValue.totalOpportunities, 'confidential opportunities');
} catch (error) {
  console.error('Access denied:', error.message);
}

React Hook for Confidential Access

import { useState, useEffect } from 'react';

interface UseConfidentialOpportunitiesResult {
  opportunities: ConfidentialOpportunity[];
  loading: boolean;
  error: string | null;
  pagination: {
    currentPage: number;
    totalPages: number;
    hasNextPage: boolean;
    hasPreviousPage: boolean;
  };
  loadPage: (page: number) => void;
  search: (filter: string) => void;
  sort: (sortBy: string) => void;
}

function useConfidentialOpportunities(): UseConfidentialOpportunitiesResult {
  const [opportunities, setOpportunities] = useState<ConfidentialOpportunity[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const [pagination, setPagination] = useState({
    currentPage: 1,
    totalPages: 0,
    hasNextPage: false,
    hasPreviousPage: false
  });
  const [filters, setFilters] = useState({
    page: 1,
    limit: 20,
    sort: 'createdAt:desc',
    filter: ''
  });

  const fetchOpportunities = async () => {
    try {
      setLoading(true);
      setError(null);
      
      const result = await getConfidentialOpportunities(filters);
      
      setOpportunities(result.opportunities);
      setPagination(result.pagination);
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown error');
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchOpportunities();
  }, [filters]);

  const loadPage = (page: number) => {
    setFilters(prev => ({ ...prev, page }));
  };

  const search = (filter: string) => {
    setFilters(prev => ({ ...prev, filter, page: 1 }));
  };

  const sort = (sortBy: string) => {
    setFilters(prev => ({ ...prev, sort: sortBy, page: 1 }));
  };

  return {
    opportunities,
    loading,
    error,
    pagination,
    loadPage,
    search,
    sort
  };
}

// Usage in component
function ConfidentialOpportunitiesPage() {
  const { 
    opportunities, 
    loading, 
    error, 
    pagination, 
    loadPage, 
    search, 
    sort 
  } = useConfidentialOpportunities();

  if (loading) return <div>Loading confidential opportunities...</div>;
  if (error) return <div>Access Error: {error}</div>;

  return (
    <div className="confidential-opportunities">
      <header className="confidential-header">
        <h1>🔒 Confidential Opportunities</h1>
        <p>Exclusive access to premium opportunities</p>
      </header>

      <div className="controls">
        <input
          type="text"
          placeholder="Search confidential opportunities..."
          onChange={(e) => search(e.target.value)}
          className="search-input"
        />
        
        <select onChange={(e) => sort(e.target.value)} className="sort-select">
          <option value="createdAt:desc">Newest First</option>
          <option value="budget:desc">Highest Budget</option>
          <option value="expirationDate:asc">Expiring Soon</option>
          <option value="title:asc">Alphabetical</option>
        </select>
      </div>

      <div className="opportunities-grid">
        {opportunities.map(opportunity => (
          <div key={opportunity.id} className="confidential-opportunity-card">
            <div className="confidential-badge">🔒 CONFIDENTIAL</div>
            
            <h3>{opportunity.title}</h3>
            <p>{opportunity.briefDescription}</p>
            
            <div className="opportunity-details">
              <div className="budget">
                💰 {opportunity.budget?.min?.toLocaleString()} - {opportunity.budget?.max?.toLocaleString()} {opportunity.budget?.currency}
                {opportunity.budget?.equity && (
                  <span className="equity"> + {opportunity.budget.equity} equity</span>
                )}
              </div>
              
              <div className="location">📍 {opportunity.location}</div>
              <div className="category">🏷️ {opportunity.category}</div>
            </div>

            {opportunity.confidentialDetails && (
              <div className="confidential-details">
                <h4>Confidential Details</h4>
                {opportunity.confidentialDetails.fundingStage && (
                  <p>Funding: {opportunity.confidentialDetails.fundingStage}</p>
                )}
                {opportunity.confidentialDetails.teamSize && (
                  <p>Team: {opportunity.confidentialDetails.teamSize}</p>
                )}
              </div>
            )}

            <div className="tags">
              {opportunity.tags.map(tag => (
                <span key={tag} className="confidential-tag">#{tag}</span>
              ))}
            </div>

            <button className="apply-confidential">Apply Confidentially</button>
          </div>
        ))}
      </div>

      <div className="pagination">
        <button 
          onClick={() => loadPage(pagination.currentPage - 1)}
          disabled={!pagination.hasPreviousPage}
        >
          Previous
        </button>
        
        <span>Page {pagination.currentPage} of {pagination.totalPages}</span>
        
        <button 
          onClick={() => loadPage(pagination.currentPage + 1)}
          disabled={!pagination.hasNextPage}
        >
          Next
        </button>
      </div>
    </div>
  );
}

cURL Examples

# Get confidential opportunities (requires confidential token)
curl -X GET "https://ring.ck.ua/api/confidential/opportunities" \
  -H "Authorization: Bearer YOUR_CONFIDENTIAL_TOKEN"

# Search for executive roles
curl -X GET "https://ring.ck.ua/api/confidential/opportunities?filter=cto%20ceo%20executive" \
  -H "Authorization: Bearer YOUR_CONFIDENTIAL_TOKEN"

# Get high-budget opportunities
curl -X GET "https://ring.ck.ua/api/confidential/opportunities?sort=budget:desc&limit=5" \
  -H "Authorization: Bearer YOUR_CONFIDENTIAL_TOKEN"

# Paginate through results
curl -X GET "https://ring.ck.ua/api/confidential/opportunities?page=2&limit=10" \
  -H "Authorization: Bearer YOUR_CONFIDENTIAL_TOKEN"

Python Example

import requests
from typing import Dict, List, Optional

class ConfidentialOpportunitiesClient:
    def __init__(self, token: str, base_url: str = "https://ring.ck.ua"):
        self.token = token
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json"
        }
    
    def get_opportunities(
        self,
        page: int = 1,
        limit: int = 20,
        sort: str = "createdAt:desc",
        filter_text: str = "",
        start_after: Optional[str] = None
    ) -> Dict:
        """Fetch confidential opportunities with filtering and pagination"""
        
        params = {
            "page": page,
            "limit": limit,
            "sort": sort
        }
        
        if filter_text:
            params["filter"] = filter_text
        
        if start_after:
            params["startAfter"] = start_after
        
        response = requests.get(
            f"{self.base_url}/api/confidential/opportunities",
            headers=self.headers,
            params=params
        )
        
        if response.status_code == 401:
            raise PermissionError("Unauthorized - check your token")
        elif response.status_code == 403:
            raise PermissionError("Access denied - confidential role required")
        elif response.status_code != 200:
            response.raise_for_status()
        
        return response.json()
    
    def search_executive_roles(self) -> List[Dict]:
        """Search for executive-level opportunities"""
        result = self.get_opportunities(
            filter_text="cto ceo vp executive",
            sort="budget:desc"
        )
        return result["opportunities"]
    
    def get_high_value_opportunities(self, min_budget: int = 200000) -> List[Dict]:
        """Get opportunities with high compensation"""
        result = self.get_opportunities(sort="budget:desc", limit=50)
        
        # Filter by minimum budget (client-side filtering)
        high_value = []
        for opp in result["opportunities"]:
            if opp.get("budget", {}).get("min", 0) >= min_budget:
                high_value.append(opp)
        
        return high_value

# Usage
try:
    client = ConfidentialOpportunitiesClient("your_confidential_token")
    
    # Get executive roles
    executive_roles = client.search_executive_roles()
    print(f"Found {len(executive_roles)} executive opportunities")
    
    # Get high-value opportunities
    high_value = client.get_high_value_opportunities(min_budget=300000)
    print(f"Found {len(high_value)} high-value opportunities")
    
    for opp in high_value[:3]:  # Show top 3
        budget = opp.get("budget", {})
        print(f"- {opp['title']}: ${budget.get('min', 0):,} - ${budget.get('max', 0):,}")
        
except PermissionError as e:
    print(f"Access denied: {e}")
except Exception as e:
    print(f"Error: {e}")

Security Features

Enhanced Protection Measures

1. Role-Based Access Control

   • Only CONFIDENTIAL and ADMIN roles can access
   • Real-time role verification on each request
   • Session validation with role checking

2. No Caching Policy

   • force-dynamic route configuration
   • No browser or CDN caching
   • Fresh data on every request

3. Audit Logging

   • All access attempts logged
   • User ID, timestamp, and IP tracking
   • Security monitoring and alerting

4. Data Encryption

   • Enhanced encryption for confidential data
   • Secure transmission protocols
   • Protected file attachments

5. Rate Limiting

   • Stricter limits for confidential endpoints
   • 60 requests per minute maximum
   • IP-based and user-based limiting

Compliance & Privacy

• GDPR Compliance: Data protection and user rights
• SOC 2 Type II: Security and availability controls
• ISO 27001: Information security management
• NDA Requirements: Legal protection for sensitive information

Business Use Cases

Executive Recruitment

// Search for C-level positions
const executiveRoles = await getConfidentialOpportunities({
  filter: 'ceo cto cfo coo',
  sort: 'budget:desc',
  limit: 10
});

Investment Opportunities

// Find investment and funding opportunities
const investments = await getConfidentialOpportunities({
  filter: 'investment funding venture capital',
  sort: 'createdAt:desc'
});

Strategic Partnerships

// Discover partnership opportunities
const partnerships = await getConfidentialOpportunities({
  filter: 'partnership collaboration joint venture',
  sort: 'expirationDate:asc'
});

Stealth Startups

// Access stealth startup opportunities
const stealthOpps = await getConfidentialOpportunities({
  filter: 'stealth startup founding team',
  sort: 'budget:desc'
});

Error Handling Best Practices

Client-Side Error Handling

async function safeGetConfidentialOpportunities(params: any) {
  try {
    return await getConfidentialOpportunities(params);
  } catch (error) {
    if (error.message.includes('Unauthorized')) {
      // Redirect to login
      window.location.href = '/login';
    } else if (error.message.includes('Permission denied')) {
      // Show upgrade prompt
      showUpgradeToConfidentialModal();
    } else {
      // Show generic error
      showErrorMessage('Failed to load opportunities');
    }
    throw error;
  }
}

Retry Logic

async function getConfidentialOpportunitiesWithRetry(params: any, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await getConfidentialOpportunities(params);
    } catch (error) {
      if (attempt === maxRetries || error.message.includes('Permission denied')) {
        throw error;
      }
      
      // Wait before retry (exponential backoff)
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

Related Endpoints

• Regular Opportunities - Standard opportunity listings
• Opportunity Details - Individual opportunity access
• Create Opportunity - Create new opportunities
• User Role Management - Role assignment and upgrades

Changelog

• v1.0.0 - Initial confidential opportunities implementation
• v1.1.0 - Added advanced filtering and search capabilities
• v1.2.0 - Enhanced security measures and audit logging
• v1.3.0 - Added pagination and cursor-based navigation
• v1.4.0 - Improved role-based access controls and compliance features