- API Reference
- Authentication
API Reference
Authentication
JWT Bearer token authentication and security requirements for MasonHub API
Authentication & Security
All MasonHub API endpoints are secured using JWT (JSON Web Token) encrypted Bearer tokens, providing secure authentication and authorization for all API operations.
Security Requirements
HTTPS Required
All API requests must use HTTPS encryption
Bearer Token
Every request must include a valid JWT bearer token
Runtime Decryption
Tokens are encrypted and only decrypted at runtime
No Database Storage
Tokens are matched at runtime, not stored in databases
Authentication Headers
Include your bearer token in the Authorization header of all requests:
Authorization: Bearer your_jwt_token_here
Content-Type: application/json
Example API Request
curl -X GET "https://api.masonhub.co/{account_slug}/api/v1/orders" \
-H "Authorization: Bearer your_jwt_token_here" \
-H "Content-Type: application/json"
Security Scheme Details
| Property | Value |
|---|---|
| Security Scheme Type | HTTP |
| HTTP Authorization Scheme | bearer |
| Bearer Format | JWT |
| Encryption | Runtime decryption |
Token Management
Obtaining Tokens
Tokens are provided by your MasonHub integration team during the onboarding process. Contact integration-support@masonhub.co to request access credentials.
Token Generation API
The token generation endpoint requires special permissions and is typically used only during initial setup.
POST /secrets
Content-Type: application/json
{
"secret_phrase": "Your secure secret phrase"
}
Token Security Best Practices
Webhook Callback Security
For webhook endpoints, implement additional security measures:
Callback Token Verification
Register callbacks with verification tokens:
{
"url": "https://api.clienturl.com/api/orderEvent",
"message_type": "orderEvent",
"api_version": "1.0",
"token": "your_encrypted_verification_token"
}
Webhook Security Best Practices
Use HTTPS
Ensure all callback URLs use HTTPS encryption
Verify Tokens
Validate the verification token in callback payloads
IP Allowlisting
Consider restricting access to known MasonHub IP addresses
Signature Verification
Implement signature verification for critical callbacks
Error Responses
Authentication Errors
Common authentication error responses:
{
"error": {
"code": "UNAUTHORIZED",
"message": "Authorization header missing"
}
}
Environment-Specific Authentication
Sandbox
Production
Base URL: https://sandbox.masonhub.co/{account_slug}/api/v1/
Purpose: Development and testing
Token Type: Sandbox-specific JWT tokens
Rate Limits: More lenient for testing
Troubleshooting Authentication
Common Issues
Support
For authentication and security questions: