Authentication
Authentication explains how an external client reaches SHM on port 882, identifies its API user, and protects the key that proves that identity.
Where to find it: Documentation > Hosting Manager > API > Authentication.
Available to: Anyone may read this page. Root creates provider identities; reseller and account identities remain limited by their assigned role, ownership, scopes, and source policy.
What this page does
External API requests use a dedicated identity and key. Authentication proves who is calling; it does not grant authority outside that identity's normal SHM role.
Before you start
Use https://panel.example.com:882 as the Engine origin. Create a separate key for each integration purpose, keep it out of source code and browser-side JavaScript, and record its owner and rotation plan.
Required headers
| Header | When required | Description | Example |
|---|---|---|---|
X-Api-User | Every external protected request | The configured API identity. SHM derives root, reseller, or user scope from this identity. | automation-root or the assigned account user. |
X-Api-Key | Every external protected request | The secret key for that identity. Active/revoked state, scopes, and source policy are enforced. | YOUR_API_KEY. |
Accept | Recommended | Requests a JSON response. | application/json. |
Content-Type | When a JSON body is sent | Declares the request body format. | application/json. |
Minimal authenticated check
curl -sS 'https://panel.example.com:882/v1/auth/check' \
-H 'X-Api-User: YOUR_API_USER' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Accept: application/json'What a valid key does not do
- It does not turn a user into root.
- It does not let a reseller reach an unowned account.
- It does not enable a feature disabled by policy or missing services.
- It does not make a private
/v1/internal/...route public. - It does not make an unsafe mutation safe to retry.
Key hygiene
- Store keys in a server-side secret manager or protected environment configuration.
- Restrict source IPs where the identity supports it.
- Use separate keys for production, staging, billing, monitoring, and support.
- Rotate on staff changes, suspected exposure, ownership transfer, or integration retirement.
- Revoke first and investigate when a key may have leaked; hope is not a credential-control mechanism.
How to use it
- Create or select the API identity in the correct SHM scope.
- Save the key once in protected storage.
- Call
https://panel.example.com:882/v1/auth/check. - Confirm the returned identity and role.
- Grant only the endpoint scopes required by the integration and test from its real source address.
Result and next check
The client authenticates on port 882, SHM reports the expected role and identity, and requests outside the assigned boundary are rejected.
Theme color