MachineQ Developer Documentation logo DOCS
Back to Docs

Authentication & API Access

Every MQcentral API call must carry a valid OAuth2 access token. Read this guide before building production code — it covers the credential lifecycle, token handling, the permission model, and the failure modes you encounter while wiring up your first client.

The Authorization Model

MQcentral supports two ways to authenticate: client credentials for machine-to-machine API access, and username/password login for browsing the MQcentral web application.

The authorization server is hosted at https://identity.machineq.net. All token requests and authorization code flows go to that domain, not to the API server at https://api.machineq.net.

Obtaining an Access Token

The client credentials flow is a single POST:

Fetch the access token
export MQ_CLIENT_ID="YOUR_CLIENT_ID"
export MQ_CLIENT_SECRET="YOUR_CLIENT_SECRET"

curl -sS -X POST https://identity.machineq.net/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$MQ_CLIENT_ID" \
  -d "client_secret=$MQ_CLIENT_SECRET"

The response:

Inspect the token response
{
  "access_token":"eyJhbGciOiJ...",
  "scope":"*",
  "expires_in":86400,
  "token_type":"Bearer"
}

Pass the token in the Authorization header of every HTTP request you make:

Set the authorization header
curl -sS -X GET https://api.machineq.net/your/endpoint \
  -H "Authorization: Bearer eyJhbGciOi..." \
  ...

Token Lifecycle

Tokens expire after approximately 24 hours (expires_in: 86400). Your client must handle re-authentication. Two patterns are common, and both are acceptable:

Lazy refresh — catch the first 401, request a new token, and retry the original call once. Simple and robust for low-volume workloads.

Proactive refresh — track expires_in and request a new token a few minutes before expiry. Required for high-volume workloads where 401-and-retry doubles your error rate.

Cache the token in memory and reuse it across requests. Do not request a new token on every API call — that puts unnecessary load on the auth service and may trigger rate limits.

Storing Secrets Safely

  • Never commit client_secret to git. Pre-commit hooks like gitleaks catch the obvious cases.
  • In production, load secrets from a vault (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, GCP Secret Manager) — not from environment variables baked into a container image.
  • Rotate credentials at least quarterly. Schedule it; don't wait for an incident.

Common Failure Modes

Symptom Likely cause
401 invalid_token immediately on a fresh token Clock skew between your host and the auth server. Check NTP.
401 invalid_token after ~24 hours Token expired. Re-authenticate.
403 with a valid scope Tenant mismatch. The credential is bound to a different tenant than the resource you're accessing.
Intermittent 401 under load You're racing token refresh across multiple workers. Use a shared token cache or a leader-elected refresher.
429 Too Many Requests on the token endpoint You're requesting a new token too frequently. Cache the token and reuse it for its full expires_in duration (~24 hours) rather than fetching a new one per API call.

What's Next?

Roles & Permissions Gateway & Network Provisioning