MQInsights Developer Documentation logo DOCS
Back to Docs

Authentication

The MQinsights API uses OAuth 2.0 client credentials grant flow for authentication, a server-to-server flow that doesn't require user interaction.

Important: The authentication URL is environment-specific and must be configurable, not hardcoded in your application.

Authentication Domain

The authentication domain follows this pattern:

code
{{AUTH0_DOMAIN}} = https://auth.<instance>.mqlocate.net/

Replace <instance> with your specific environment instance.

Required HTTP Headers

All API requests must include these headers:

Header Value Description Required
Content-Type application/json Request payload format Yes
X-B3-TraceId 32 lower-hex chars Overall trace ID (generated by your app) Yes
X-B3-SpanId 16 lower-hex chars Current operation trace ID (generated by your app) Yes

Distributed Tracing: The X-B3-TraceId and X-B3-SpanId headers are used for distributed tracing. Generate unique values for each request to enable request tracking across systems.

Requesting a Token

POST {{AUTH0_DOMAIN}}/oauth/token implements the OAuth 2.0 client credentials grant to obtain an access token.

Parameters

Parameter Type Location Required Description
client_id string body Yes Your client ID (provided separately by MQinsights)
client_secret string body Yes Your client secret (provided separately by MQinsights)
audience string body Yes API audience identifier (provided separately by MQinsights)
grant_type string body Yes Must be client_credentials

Security Warning: $CLIENT_SECRET must be protected like a password. Never commit credentials to source control; store them as environment variables. All values are environment-specific and must be configurable.

Example Request

bash
curl -sS -X POST "$AUTH0_DOMAIN/oauth/token" \
  -H "Content-Type: application/json" \
  -H "X-B3-TraceId: 1234567890abcdef1234567890abcdef" \
  -H "X-B3-SpanId: 1234567890abcdef" \
  -d '{
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET",
    "audience": "$AUDIENCE",
    "grant_type": "client_credentials"
  }'

Example Response

json
{
  "access_token": "eyJdz29413a...k4245slaUWw",
  "token_type": "Bearer",
  "expires_in": 86400
}

Response Codes

Code Status Description
200 OK Token successfully issued
400 Bad Request Invalid request format or parameters
401 Unauthorized Invalid credentials
415 Unsupported Media Type Content-Type must be application/json
5xx Internal Server Error Service temporarily unavailable

Using the Access Token

Once you receive an access token:

  • Persist the access_token: you'll need it for all API requests.
  • Monitor the expires_in value (in seconds): indicates token lifetime.
  • Refresh the token when it expires or after receiving a 401 Unauthorized response.
  • Include the token in all API requests using the Authorization header:
code
Authorization: Bearer {access_token}

Token Expiration: Tokens typically expire after 24 hours (86400 seconds). Implement automatic token refresh logic in your application to handle expiration gracefully.

API Domain

The API domain is the base URL for all REST API calls.

Important: {{API_DOMAIN}} must be configurable per environment and never hardcoded in your application.

code
{{API_DOMAIN}} = https://track.<instance>.mqlocate.net/api/v1.0

Replace <instance> with your specific environment instance. All API endpoints are relative to it:

code
POST {{API_DOMAIN}}/integrations/asset/upsert
GET {{API_DOMAIN}}/integrations/asset/{customer_reference}/location
GET {{API_DOMAIN}}/integrations/sensor-data-lite/

What's Next?

Getting Started Asset Management