​
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

PropertyValue
Security Scheme TypeHTTP
HTTP Authorization Schemebearer
Bearer FormatJWT
EncryptionRuntime 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

1

Use HTTPS

Ensure all callback URLs use HTTPS encryption

2

Verify Tokens

Validate the verification token in callback payloads

3

IP Allowlisting

Consider restricting access to known MasonHub IP addresses

4

Signature Verification

Implement signature verification for critical callbacks

​
Error Responses

​
Authentication Errors

Common authentication error responses:

​
Environment-Specific Authentication

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:

Integration Support

Technical authentication questions

Email: integration-support@masonhub.co

General Support

Account and access questions

Email: support@masonhub.co

API ReferenceCatalog Management