Authentication

Bearer token authentication is used to secure the external API.

Access model

ReadPublicApi is required for queries and GraphiQL access. WritePublicApi is required for mutations such as webhook registration and dev-mode test mutations. These scopes are set on the API key and are independent of your user account's permissions, so mutations need write scope on the key itself as well as on your user.

The API uses API keys with bearer tokens. OAuth and service accounts (Azure or Google) are not part of the model, so there is nothing to provision on your identity platform.

Token lifetime

Tokens are short-lived: typically 15 minutes. Always use the returned expiresIn value (seconds) rather than assuming a fixed lifetime.

• Cache the token and reuse it until shortly before expiry, rather than authenticating per request.
• Re-authenticate with your key and secret to get a fresh token. There is no separate refresh endpoint.
• A 401 from the GraphQL endpoint usually means the token has expired.

If you need to inspect the expiry inside the token itself, decode the JWT with your platform tooling or a utility such as jwt.io.

Obtain your bearer token

Post a valid API key and secret to:

https://core-api.app.xysense.io/api/v1/auth

POST https://core-api.app.xysense.io/api/v1/auth
Accept: application/json
Content-Type: application/json

{
  "ApiKey": "<your key>",
  "ApiSecret": "<your secret>"
}

Example auth response

{
  "idToken": "<your token>",
  "expiresIn": 900
}

expiresIn is the token lifetime in seconds.

Attach the bearer token

Once you have the token, add it to the Authorization header on every GraphQL request.

POST https://core-api.app.xysense.io/api/external/query
Authorization: Bearer <idToken>
Accept: application/json
Content-Type: application/json
Accept-Encoding: gzip

{
  "query": "query Buildings { buildings { id name } }"
}

Example API request body

{
  "query": "query Buildings($nameLike: String) { buildings(nameLike: $nameLike) { id name } }",
  "variables": { "nameLike": "Example" },
  "operationName": "Buildings"
}

variables must be a JSON object (not a string). operationName is required when the document contains a named operation.

Manage API keys

Manage API keys in the Admin Console:

https://app.xysense.io/settings/apiaccess

Key points:

• The API key name is derived from the description and must be unique when created.
• Use ReadPublicApi for query-only clients.
• Use WritePublicApi only when the integration needs mutations such as webhook registration or dev-mode test traffic.
• Follow least privilege.
• The API secret is shown once at creation time and cannot be recovered later.

Partner accounts

If you access XY Sense as a partner, your user operates across multiple customers, while API keys, API Explorer sessions, and webhooks are all scoped to a single customer.

• Open the customer first (select the customer in the Admin Console, then choose Open as Customer), and create API keys or webhooks from within that customer context.
• Explorer deep links shared with you also assume a customer context, so open the customer before following them.
• Repeat key creation per customer when you integrate the same product for several customers.

Operational notes

• Refresh tokens proactively based on the returned expiresIn value.
• All API requests must be HTTPS and JSON encoded.
• Compression is useful for larger polling windows and change batches.