Quickstart

This page takes you from nothing to a successful API response. Everything else in these docs builds on these four steps.

Before you start

• Authentication uses API keys and short-lived bearer tokens. OAuth and service accounts are not part of the model, so there is nothing to provision on your identity platform.
• The XY Sense features you plan to use (Occupancy API, Analytics API, Webhooks) need to be enabled for your organisation. If a query returns an access-disabled error, your XY Sense representative can enable the feature for you.
• API keys and user permissions are scoped separately. Your user account needs read/write access to the external API to use the API Explorer and manage API access to create keys, and each key also carries its own read or read/write scope. Mutations need write scope on the key itself, in addition to your user account's permissions.

1. Create an API key

In the Admin Console, go to https://app.xysense.io/settings/apiaccess and create a key.

• ReadPublicApi suits query-only clients. Add WritePublicApi when you need mutations (webhook registration, test-data generation).
• The API secret is shown once at creation time, so store it securely.

2. Exchange the key for a bearer token

curl -s https://core-api.app.xysense.io/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{ "ApiKey": "<your key>", "ApiSecret": "<your secret>" }'

Response:

{
  "idToken": "eyJraWQiOiJ...",
  "expiresIn": 900
}

Tokens are short-lived, typically 15 minutes (expiresIn is in seconds). Cache the token and re-authenticate shortly before it expires, rather than fetching a new token per request. There is no separate refresh endpoint: re-authenticating with your key and secret is the refresh.

3. Run your first query

curl -s https://core-api.app.xysense.io/api/external/query \
  -H "Authorization: Bearer <idToken>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "query Buildings { buildings { id name floors { id name } } }" }'

Response:

{
  "data": {
    "buildings": [
      {
        "id": "0b26f8f3-5d1c-4c6a-9d3e-1a2b3c4d5e6f",
        "name": "1 Example Street",
        "floors": [{ "id": "a2961d46-971f-4ce1-a66e-7ee7bdb2a204", "name": "Level 12" }]
      }
    ]
  }
}

If you get data back, your credentials, token handling, and connectivity are all working.

4. Explore from here

• Open the interactive API Explorer. It authenticates with your user session and is the fastest way to build and validate queries.
• Read Choosing the right API to pick between live occupancy, analytics, and webhooks for your workload.
• If you have no live sensors yet, see Test data without live sensors.
• Prefer Postman? Import the Postman collection for a runnable version of these patterns.

Troubleshooting

Symptom	Where to look
401 on the GraphQL endpoint	The token has usually expired (they last about 15 minutes). Re-authenticate and retry, and check the Authorization: Bearer header.
401 on the auth endpoint	The key or secret is incorrect. Secrets are shown only at creation, so create a new key if the secret has been lost.
You are not authorized to access the '...' field	The API key's scope. Mutations need WritePublicApi on the key itself, in addition to your user account's permissions.
An access-disabled error mentioning Analytics or Occupancy API	The feature has not been enabled for your organisation yet. Your XY Sense representative can enable it.