Authentication
Every request except token issuance must carry an Authorization header. Use short-lived bearer tokens issued from your API key and secret.
Preferred authentication
For new remote integrations, Masttro recommends short-lived, revocable authorization using the supported bearer/OAuth flow. Credentials should be issued to a dedicated integration identity where available and should be limited to the clients, products and MCP tools required by that integration.
Bearer tokens must be protected as secrets. Applications should obtain, refresh and revoke them through the supported authentication flow rather than storing long-lived Masttro credentials in source code or shared configuration files. MCP clients that support it should use OAuth.
Bearer tokens
Exchange your credentials for a JSON Web Token at POST /Auth/Token, then send it on every request:
| Property | Value |
|---|---|
| Lifetime | 60 minutes. expires_in in the token response gives the exact number of seconds. |
| Clock skew | None. A token is rejected the second it expires, so refresh a minute or two early. |
| Scope | The token carries your Masttro user and license. It grants the same data access as your API key. |
| Refresh | There is no refresh token. Call POST /Auth/Token again with your key and secret. |
For token caching and automatic refresh, see the reusable client.
Authentication errors
| Status | When | Body |
|---|---|---|
400 | POST /Auth/Token without apiKey or apiSecret | "apiKey and apiSecret are required." |
401 | POST /Auth/Token with wrong credentials | "Invalid credentials." |
401 | Missing, malformed or expired Authorization header on any other endpoint | Empty |
401 | Endpoint not included in your license | Unauthorized. Invalid license. See License types. |
When a request that previously worked starts returning an empty 401, your token has most likely expired. Request a new one and retry once.
Security best practices
- Call the API from a server you control. Never embed the API secret in a browser, mobile app or spreadsheet that others can open.
- Keep tokens in memory only, and request a new one rather than persisting them.
- Use one API user per integration so access can be reviewed and revoked independently.
- Every authenticated request is recorded in Masttro's audit log against your API user.