Quick Start Guide

Get started with the SoshiaConnect API in minutes. This guide walks you through the essential steps to begin making API calls.

Overview

The SoshiaConnect API uses a dual authentication system combining User credentials and API Keys. Both components are required for executing API endpoints, providing enhanced security for your integrations.

API Base URL: https://api.soshiaconnect.com/api

Prerequisites

• Basic understanding of REST APIs
• A tool for making HTTP requests (curl, Postman, or your preferred programming language)
• Access to email for account verification

---

Step 1: Create Your Account

Sign up for a SoshiaConnect account through the web portal:

Portal URL: https://soshiaconnect.soshianest.ai/auth/signup/

1. Navigate to the registration page
2. Complete the registration form with your details
3. Submit your application

Step 2: Verify Your Account

After registration:

1. Check your email inbox for a verification message from SoshiaConnect
2. Follow the verification instructions in the email
3. Complete the verification process to activate your account

tip

Make sure to check your spam/junk folder if you don't see the verification email within a few minutes.

Step 3: Generate API Keys

Once your account is verified:

1. Log in to the SoshiaConnect portal at https://soshiaconnect.soshianest.ai/
2. Navigate to API Keys section: https://soshiaconnect.soshianest.ai/api-keys
3. Click Generate New API Key
4. Provide a descriptive name for your API key (e.g., "Production Server", "Development Environment")
5. Associate the API key with a verified user account
6. Save the generated API key securely

Security Best Practice

Store your API keys securely and never commit them to version control. Treat them like passwords—they provide access to your account's resources.

Step 4: Authenticate and Make Your First API Call

The SoshiaConnect API requires both authentication components for each request:

1. Bearer Token (from user login)
2. API Key (generated from the portal)

Get Your Access Token

First, authenticate to obtain your Bearer token:

curl -X POST https://api.soshiaconnect.com/api/auth/login \
  -H "Content-Type: multipart/form-data" \
  -F "email=your@email.com" \
  -F "password=YourSecurePassword"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "user": {
    "id": 1,
    "email": "your@email.com",
    "full_name": "Your Name"
  }
}

Save the access_token for subsequent API requests.

Make an Authenticated Request

Use both the Bearer token and API key together:

curl https://api.soshiaconnect.com/api/route-access/all-routes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

Authentication Header Format

• Authorization Header: Bearer <access_token>
• API Key Header: X-API-Key: <your_api_key>

Both headers are required for all authenticated endpoints.

Step 5: Explore Available Routes

Retrieve the list of available shipping routes:

curl https://api.soshiaconnect.com/api/route-access/all-routes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

Response Example:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "origin": "Shanghai",
      "destination": "Los Angeles",
      "carrier": "Maersk Line",
      "transit_days": 14
    },
    // ... more routes
  ]
}

---

Code Examples

JavaScript (Node.js)

const axios = require('axios');

const API_BASE = 'https://api.soshiaconnect.com/api';
const API_KEY = 'your_api_key_here';

// Login to get access token
async function login(email, password) {
  const formData = new FormData();
  formData.append('email', email);
  formData.append('password', password);

  const response = await axios.post(`${API_BASE}/auth/login`, formData);
  return response.data.access_token;
}

// Fetch available routes
async function getRoutes(token) {
  const response = await axios.get(`${API_BASE}/route-access/all-routes`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': API_KEY
    }
  });
  return response.data;
}

// Usage
(async () => {
  try {
    const token = await login('your@email.com', 'password');
    const routes = await getRoutes(token);
    console.log('Available routes:', routes);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
})();

Python

import requests

API_BASE = 'https://api.soshiaconnect.com/api'
API_KEY = 'your_api_key_here'

def login(email, password):
    """Authenticate and retrieve access token"""
    response = requests.post(
        f'{API_BASE}/auth/login',
        data={'email': email, 'password': password}
    )
    response.raise_for_status()
    return response.json()['access_token']

def get_routes(token):
    """Fetch all available shipping routes"""
    response = requests.get(
        f'{API_BASE}/route-access/all-routes',
        headers={
            'Authorization': f'Bearer {token}',
            'X-API-Key': API_KEY
        }
    )
    response.raise_for_status()
    return response.json()

# Usage
try:
    token = login('your@email.com', 'password')
    routes = get_routes(token)
    print('Available routes:', routes)
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

PHP

<?php

$apiBase = 'https://api.soshiaconnect.com/api';
$apiKey = 'your_api_key_here';

// Login to get access token
function login($email, $password) {
    global $apiBase;

    $ch = curl_init("$apiBase/auth/login");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, [
        'email' => $email,
        'password' => $password
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $response['access_token'];
}

// Fetch available routes
function getRoutes($token, $apiKey) {
    global $apiBase;

    $ch = curl_init("$apiBase/route-access/all-routes");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $token",
        "X-API-Key: $apiKey"
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = json_decode(curl_exec($ch), true);
    curl_close($ch);

    return $response;
}

// Usage
try {
    $token = login('your@email.com', 'password');
    $routes = getRoutes($token, $apiKey);
    print_r($routes);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

---

Authentication Summary

Component	Where to Get	How to Use
User Credentials	Portal registration	Login via /auth/login to get Bearer token
API Key	API Keys Portal	Include in X-API-Key header
Bearer Token	Login response	Include in Authorization: Bearer <token> header

All authenticated endpoints require BOTH headers:

• Authorization: Bearer <access_token>
• X-API-Key: <your_api_key>

---

Next Steps

Now that you've successfully authenticated and made your first API call, explore:

• Authentication Guide - Deep dive into authentication mechanisms
• API Reference - Complete endpoint documentation
• Routes and Subscriptions - Understanding the subscription model
• Error Handling - Learn how to handle API errors gracefully
• Rate Limits - Understand API usage quotas

Need Help?

• API Reference: /api
• Email Support: support@soshiaconnect.com
• Portal: https://soshiaconnect.soshianest.ai/