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