Authentication
The Unified Order Service API implements enterprise-grade authentication mechanisms to ensure secure access to order management operations. Two authentication methods are supported: API Key authentication for service-to-service integrations and MSAL (Microsoft Authentication Library) for user-based access control.
Authentication Methods Overview
API Key Authentication
API Key authentication provides a straightforward authentication mechanism suitable for server-to-server integrations, automated processes, and service accounts. Each API key carries specific permissions and channel access restrictions, enabling fine-grained access control.
MSAL Authentication
MSAL authentication integrates with Azure Active Directory to provide user-based authentication with Attribute-Based Access Control (ABAC). This method is designed for applications requiring individual user identification, role-based permissions, and context-aware access restrictions.
API Key Authentication
Implementation
API keys are transmitted via the HTTP Authorization header using the Bearer token scheme:
Authorization: Bearer YOUR_API_KEY
Permission Scopes
API keys are assigned one of three permission levels:
| Scope | Operations Allowed | Use Case |
|---|---|---|
| Read | GET requests only | Reporting, monitoring, read-only integrations |
| Write | GET, POST, PUT, PATCH | Standard integration operations |
| Admin | All operations including DELETE | Administrative tools, complete system access |
Channel Restrictions
Each API key is associated with specific channels, restricting data access to only those channels. This ensures data isolation between different sales channels and business units.
Request Example
curl -X GET "https://api.example.com/v1/orders?channel_id=CHANNEL_ID" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
MSAL Authentication
Overview
MSAL authentication provides user-based access control integrated with Azure Active Directory. User permissions are determined by Azure AD attributes, enabling dynamic access control based on organizational roles and responsibilities.
Permission Mapping
Azure AD attributes map to UOS access levels according to the following scheme:
| Azure AD Permission | UOS Access Level | Allowed Operations |
|---|---|---|
appPicker, appDriver, appDispatch, appStoreManager | Read | GET operations |
order, place, product, assortment, route | Write | GET, POST, PUT, PATCH |
placeadmin, assortmentadmin, routeadmin | Admin | All operations |
Context-Based Access Control
MSAL authentication includes context-aware access control:
- Users are associated with specific places (stores, warehouses, fulfillment centers)
- Places are mapped to channels for data access
- Users can only access data for channels within their assigned context
- Admin users bypass context restrictions and have access to all channels
Implementation
MSAL tokens are transmitted via the HTTP Authorization header using the Bearer token scheme:
Authorization: Bearer JWT_TOKEN
Request Example
curl -X GET "https://api.example.com/v1/orders?channel_id=CHANNEL_ID" \
-H "Authorization: Bearer JWT_TOKEN" \
-H "Content-Type: application/json"
Obtaining API Credentials
API Key Provisioning
To obtain API keys:
- Contact Naveo Support at gsd@maginus.atlassian.net
- Specify the required permission scope (read, write, or admin)
- Identify the channels requiring access
- Receive the generated API key via secure channel
MSAL Configuration
MSAL authentication is configured through Azure Active Directory. Contact Naveo Support at gsd@maginus.atlassian.net to:
- Verify Azure AD account provisioning
- Confirm role assignments and permissions
- Obtain necessary context associations (places, channels)
Security Best Practices
Credential Management
Storage - Store API keys and tokens in secure credential management systems (environment variables, key vaults, secrets managers). Never commit credentials to version control systems.
Transmission - Always use HTTPS for API requests. The UOS API enforces TLS encryption for all endpoints.
Rotation - Implement regular credential rotation schedules to minimize security exposure from compromised credentials.
Access Control
Least Privilege - Request the minimum permission scope required for the intended operations. Use read-only keys when write operations are not necessary.
Scope Limitation - Restrict API key channel access to only those channels required for the integration.
Monitoring - Implement logging and monitoring of API key usage to detect unauthorized access patterns.
Error Handling
API Key Errors
| Status Code | Error Code | Description | Resolution |
|---|---|---|---|
| 401 | MISSING_API_KEY | Authorization header missing or invalid | Verify Authorization header format and API key value |
| 403 | INSUFFICIENT_SCOPE | API key lacks required permissions | Request API key with appropriate scope |
| 403 | UNAUTHORIZED_CHANNEL | API key cannot access specified channel | Verify channel ID and API key channel permissions |
MSAL Authentication Errors
| Status Code | Error Code | Description | Resolution |
|---|---|---|---|
| 401 | MISSING_AUTH | Authorization header not provided | Include valid JWT token in Authorization header |
| 401 | EXPIRED_TOKEN | JWT token has expired | Obtain new token from Azure AD |
| 401 | INVALID_TOKEN | JWT token format or signature invalid | Verify token generation and signing process |
| 403 | INVALID_AUDIENCE | Token audience doesn't match expected client | Verify Azure AD application configuration |
| 403 | INVALID_ISSUER | Token issuer not valid for tenant | Confirm Azure AD tenant configuration |
| 403 | NO_ACCESSIBLE_CHANNELS | User has context but no accessible channels | Verify user place and channel associations |
| 403 | INSUFFICIENT_SCOPE | User lacks required permission level | Request administrator to update user permissions |
Authentication Method Selection
Use API Keys For
- Service-to-service integrations requiring long-term, stable authentication
- Automated systems and batch processes without user interaction
- Webhook receivers and scheduled tasks
- External system integrations that don't support MSAL
- Background workers and queue processors
Use MSAL Authentication For
- User-facing applications (web applications, mobile apps)
- User-specific permissions based on organizational roles
- Context-based access (users restricted to specific stores/locations)
- Audit trails requiring user identification
- Token expiration and refresh capabilities
- Azure Active Directory integration requirements
Multi-API Authentication
The UOS platform provides two primary APIs, each accepting both authentication methods:
Core API
The Core API provides complete order lifecycle management, channel configuration, and administrative operations.
curl -X GET "https://api.example.com/v1/orders?channel_id=CHANNEL_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
Drone API
The Drone API provides optimized endpoints for in-store picking and fulfillment operations.
curl -X GET "https://api.example.com/dts/drone/orders?store_guid=STORE_GUID" \
-H "Authorization: Bearer YOUR_API_KEY"
Both APIs use identical authentication mechanisms and honor the same permission and scope restrictions.
Troubleshooting
Authentication Failures
Symptom: Requests return 401 Unauthorized
Diagnostic Steps:
- Verify Authorization header is present and correctly formatted
- Confirm API key or JWT token is valid and not expired
- Test credentials with a simple GET request to a known endpoint
- Review API response body for specific error codes
Symptom: Requests return 403 Forbidden
Diagnostic Steps:
- Verify API key or user has required permission scope for the operation
- Confirm channel access permissions for the requested channel
- For MSAL authentication, verify user context and place associations
- Review user Azure AD attributes and role assignments
Support Resources
For persistent authentication issues:
- Review error codes - Consult the error handling tables above
- Verify configuration - Confirm API key validity, user permissions, and channel associations
- Check logs - Review application logs for detailed error messages
- Contact support - Reach out to Naveo Support at gsd@maginus.atlassian.net with specific error details
Related Documentation
- API Keys Management - Creating and managing API keys
- Core API Reference - Complete API endpoint documentation
- Drone API Reference - In-store operations API documentation
- Webhooks - Webhook authentication configuration