API Authentication

All ShipEdge Core APIs require authentication to protect your data and ensure only authorized users can access your account. The authentication method varies depending on which API you’re using.

Quick Start

For most integrations, use REST API v4 with AccountID and API Key. This is the simplest and most secure method for OMS operations.

Why Authentication Matters

Protect Your Data

Authentication ensures only authorized users and systems can access your orders, inventory, and warehouse data.

Track API Usage

Each authenticated request is logged, allowing you to monitor API usage and troubleshoot issues.

Account Security

API keys can be regenerated if compromised, providing better security than password-based authentication.

Access Control

Different authentication methods support different access levels, from account-level to user-level permissions.

---

Authentication Methods Overview

ShipEdge Core supports different authentication methods depending on the API version and use case:

API Version	Method	Headers Required	Use Case
REST API v4 (OMS)	API Key	AccountID + Key	Order and inventory management
REST API v4 (WMS)	Master API Key	userName + Key	Warehouse operations
API v2	API Key	AccountID + Authorization or Key	Legacy integrations
eXos Mobile	JWT Tokens	Multiple headers	Mobile warehouse applications

---

REST API v4 (OMS) Authentication

REST API v4 (OMS) uses account-level API keys for authentication.

Required Headers

AccountID: [Your numeric AccountID]
Key: [Your API Key]

Getting Your Credentials

1. Log in to your ShipEdge OMS account

   Access your Order Management System account through the web interface.

2. Navigate to Preferences

   Go to My Account > Preferences in the main menu.

3. Open API Integration section

   Click on the API Integration tab in Preferences.

4. Find your credentials

   You’ll see:

   • AccountID: Your numeric account identifier
   • Key: Your API key (click “Generate new Key” if needed)

Account Requirements

Your account must meet these requirements:

• Activated: Account must be activated (Activated = 'Y')
• AccountID: Must exist in the system
• API Key: Must match the KeyAPI stored for your account

Example Request

curl -X POST https://your-instance.shipedge.com/apirest/v4/oms/ping \
  -H "AccountID: 100" \
  -H "Key: abcde12345"

Error Responses

Missing Key:

{
  "response": {
    "success": false,
    "message": "The Key is invalid or doesn't have access to this API resource"
  }
}

Missing AccountID:

{
  "response": {
    "success": false,
    "message": "The Header value is invalid. AccountID is missing or empty"
  }
}

Account Not Found:

{
  "response": {
    "success": false,
    "message": "The Header value is invalid. AccountID doesn't exist."
  }
}

Account Not Activated:

{
  "response": {
    "success": false,
    "message": "The Header value is invalid. AccountID isn't activated"
  }
}

---

REST API v4 (WMS) Authentication

REST API v4 (WMS) uses warehouse user credentials with a master API key.

Required Headers

userName: [Your warehouse username]
Key: [Master API Key]

Getting Your Credentials

1. Log in to your ShipEdge WMS account

   Access your Warehouse Management System account through the web interface.

2. Navigate to System Config

   Go to System Config in the main menu.

3. Open Preferences

   Click on Preferences in the System Config menu.

4. Go to Operations section

   Navigate to the Operations tab or section.

5. Find Master API Key

   Look for Shipedge master API Key field. If no key exists, click Generate an API Key to create one.

6. Get your Username

   Your username is the same username you use to log in to the WMS system.

User Requirements

Your WMS user account must meet these requirements:

• UserLevel: Must be level 2 (warehouse user)
• Activated: Account must be activated (Activated = 'Y')
• Username: Must match exactly (case-sensitive)

Example Request

curl -X POST https://your-instance.shipedge.com/apirest/v4/wms/ping \
  -H "userName: manager" \
  -H "Key: abcde12345"

Error Responses

Missing Key:

{
  "response": {
    "success": false,
    "message": "The Key is invalid or doesn't have access to this API resource"
  }
}

Missing Username:

{
  "response": {
    "success": false,
    "message": "The Header value is invalid. UserName is missing or empty"
  }
}

User Not Found or No Permissions:

{
  "response": {
    "success": false,
    "message": "The Header value is invalid. User doesn't exist or it has no permissions"
  }
}

User Not Activated:

{
  "response": {
    "success": false,
    "message": "The Header value is invalid. User isn't activated"
  }
}

---

API v2 Authentication

API v2 supports account-level API key authentication, similar to API v4 OMS but with slightly different header names.

Required Headers

Option 1 (Preferred):

AccountID: [Your numeric AccountID]
Authorization: [Your API Key]

Option 2 (Alternative):

AccountID: [Your numeric AccountID]
Key: [Your API Key]

Getting Your Credentials

Credentials are the same as REST API v4 (OMS):

• AccountID: Found in My Account > Preferences > API Integration
• API Key: Found in My Account > Preferences > API Integration

Account Requirements

• Activated: Account must be activated (Activated = 'Y')
• AccountID: Must exist in the system
• API Key: Must match the KeyAPI stored for your account, or match the master API key

Example Request

curl -X POST https://your-instance.shipedge.com/apiv2/endpoint \
  -H "AccountID: 100" \
  -H "Authorization: abcde12345"

Or using the alternative format:

curl -X POST https://your-instance.shipedge.com/apiv2/endpoint \
  -H "AccountID: 100" \
  -H "Key: abcde12345"

---

eXos Mobile Authentication (JWT Tokens)

eXos mobile applications use JWT (JSON Web Token) authentication with multiple headers for enhanced security.

Required Headers

Authorization: [JWT token]
Token: [Hash token]
User-Id: [User ID]
Device-Id: [Device identifier]
App: [Application name]
App-Version: [Application version]
System-Version: [System version]

How It Works

1. Login Process: User logs in through /exos-login-1 endpoint
2. Token Generation: System generates JWT tokens for the session
3. Token Validation: Each request validates both Authorization and Token headers
4. Device Tracking: Device ID is tracked for security

Example Request

curl -X POST https://your-instance.shipedge.com/apiv2/exos-v1/pp-getOrders-1 \
  -H "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "User-Id: 123" \
  -H "Device-Id: device123" \
  -H "App: eXos" \
  -H "App-Version: 1.0.0" \
  -H "System-Version: iOS 15.0"

Security Features

• JWT Tokens: Encrypted tokens that expire after a set time
• Device Validation: Each device must be registered
• Token Matching: Both Authorization and Token must match the same user
• Version Tracking: App and system versions are tracked for compatibility

---

Security Best Practices

Store Credentials Securely

Never expose API keys in public code, repositories, or client-side JavaScript. Use environment variables or secret managers.

Regenerate Keys Regularly

Periodically regenerate your API keys, especially if you suspect they may have been compromised.

Use HTTPS Only

Always use HTTPS when making API requests. Never send credentials over unencrypted connections.

Limit Key Access

Only share API keys with trusted systems and users. Revoke access immediately if compromised.

Monitor API Logs

Regularly review API logs to detect unauthorized access or unusual activity patterns.

Use Different Keys

Use different API keys for different environments (development, staging, production) when possible.

Validate Responses

Always validate API responses and handle authentication errors appropriately in your code.

Keep Keys Private

Never log API keys or include them in error messages that might be exposed to users.

---

Common Authentication Errors

Error 400 - Bad Request

Common causes:

• Missing required headers
• Empty header values
• Incorrect header names (case-sensitive)

Solution:

1. Verify all required headers are present
2. Check that header values are not empty
3. Ensure header names match exactly (case-sensitive)
4. Review API documentation for exact header requirements

Error 401 - Unauthorized

Common causes:

• Invalid API key
• Account not activated
• User not activated (WMS)
• Incorrect credentials
• Expired JWT token (mobile)

Solution:

1. Verify your API key matches exactly (no extra spaces)
2. Check that your account is activated
3. For WMS, ensure your user account is activated and has correct permissions
4. Regenerate your API key if necessary
5. For mobile apps, re-authenticate to get new tokens

Error 403 - Forbidden

Common causes:

• Insufficient permissions
• User level restrictions (WMS)
• Invalid token format (mobile)

Solution:

1. Verify your account has the necessary permissions
2. For WMS, ensure your user has UserLevel 2
3. Check that your API key has access to the requested resource
4. For mobile apps, verify token format and expiration

---

Regenerating API Keys

If you suspect your API key has been compromised or want to rotate keys for security:

OMS API Key

1. Log in to your OMS account

2. Go to My Account > Preferences

3. Click API Integration tab

4. Click “Generate new Key”

5. Confirm the action

6. Update all integrations with the new key immediately

WMS Master API Key

1. Log in to your WMS account

2. Go to System Config > Preferences

3. Navigate to Operations section

4. Click “Generate an API Key”

5. Confirm the action

6. Update all integrations with the new key immediately

Update All Integrations

After regenerating an API key, update all systems using that key immediately. Old keys will stop working once regenerated.

---

Testing Authentication

Using Ping Endpoints

The easiest way to test authentication is using the ping endpoints:

REST API v4 (OMS):

curl -X POST https://your-instance.shipedge.com/apirest/v4/oms/ping \
  -H "AccountID: 100" \
  -H "Key: abcde12345"

REST API v4 (WMS):

curl -X POST https://your-instance.shipedge.com/apirest/v4/wms/ping \
  -H "userName: manager" \
  -H "Key: abcde12345"

Expected Response:

{
  "data": {
    "status": "Successful",
    "result": "pong!"
  }
}

Using Swagger Documentation

Both REST API v4 (OMS) and REST API v4 (WMS) include interactive Swagger documentation where you can test authentication:

• OMS Swagger: https://your-instance.shipedge.com/apirest/v4/oms/docs
• WMS Swagger: https://your-instance.shipedge.com/apirest/v4/wms/docs (requires WMS session)

---

Troubleshooting

Credentials Not Working

Check:

1. Header names are correct and case-sensitive
2. No extra spaces in header values
3. Account/user is activated
4. API key matches exactly (no typos)
5. Using correct API version endpoint

Account Not Activated

Solution:

1. Contact your account administrator
2. Verify account status in Preferences
3. Check for any account restrictions
4. Ensure account is not suspended

User Permissions (WMS)

Check:

1. User has UserLevel 2 (warehouse user)
2. User account is activated
3. Username matches exactly (case-sensitive)
4. User has necessary permissions for the operation

Token Expiration (Mobile)

Solution:

1. Implement token refresh logic
2. Re-authenticate when tokens expire
3. Handle 401 errors gracefully
4. Store tokens securely and refresh before expiration

---

Related Links

• API Overview - General API information and comparison
• REST API v4 (OMS) - OMS endpoints documentation
• REST API v4 (WMS) - WMS endpoints documentation
• API v2 (Legacy) - Legacy API documentation

---

Next Step: REST API v4 (OMS) - Learn to use OMS endpoints for order and inventory management