Getting access

Short answer to the question partners usually ask: yes, your own developers can set integrations up themselves. What you need depends on which level you are at.

You want to	You need
Push data in / read data out (level 1)	A service-account credential for tv-api and a buildingId. Nothing to install.
Do it from n8n (level 2)	The same credential, plus our node package from the private registry.
Build a module (level 3)	A developer account, a sandbox API key, and the SDK from the private registry.

The integration credential

External systems authenticate to tv-api with a Keycloak service account (OAuth2 client-credentials) in the customer's tenant realm — not with a personal login and not with a long-lived static key.

curl -s -X POST \
  "$KEYCLOAK/realms/tangovision/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" | jq -r .access_token

Send the result as Authorization: Bearer … on every call. Tokens are short-lived — fetch a new one when you get a 401, which is exactly what the n8n credential does for you.

The token must carry the organization claim (tenant_id, or organizationId / org_id) — without it the API fails closed with 403 No organization context rather than showing you another tenant's data. Getting that claim onto the service account is part of issuing it, so ask for the credential rather than building one yourself.

Which role to ask for

What the integration does	Permission	Ask for the role
Read layers, spaces, telemetry	building.layers:read, graph reads	user
Create layers, upload values	building.layers:write	manager
Register webhook subscriptions	platform.webhooks:write	manager
Create and progress tickets	service-desk write	manager (or a service-desk-scoped role)

Prefer the narrowest role that covers the job — a read-only reporting integration should be a user, not a manager.

Not building-graph-writer

You will see that role in the permission tables next to manager. It is the platform's own IFC-ingestion identity and it bypasses the per-building ownership check — it is cross-tenant by design. It is not the "narrow push-only role" its name suggests, and it should not be issued to an external integration.

A sandbox first

Do not develop against a customer's production tenant. On-demand sandboxes give you an isolated tenant with its own database, a seeded building graph, and a full tv-api — see On-demand sandboxes for the whole flow, and Developer account for self-service registration and minting the tvk_… sandbox API keys in the developer portal.

Note the boundary: a developer account lives in its own realm and is deliberately isolated from tenant data. It gets you sandboxes; it does not get you into a customer's building. The integration credential above is a separate thing, issued in the customer's own realm — usually to you, by them, with our help.

What is gated today

The private registry answers 401 to anonymous requests

@tv/* packages — the SDK and the n8n nodes — live on https://npm.k8s.tangovision.dev/, which serves no anonymous downloads (verified 2026-08-04). And a registry token is not something you can mint yourself today: the developer portal issues sandbox API keys (tvk_…), which are a different credential and will not authenticate an install.

So, plainly:

Level	Blocked by the registry?
1 — HTTP	No. Nothing to install. curl, or any HTTP client you already have.
2 — n8n	Yes, until you have a registry token — the node package comes from there.
3 — SDK module	Yes, same reason.

To get a registry token, email developers@tango.vision with your developer account email, the organization you are integrating for, and which packages you need. It is a manual step on our side today; we would rather tell you that than have you spend an afternoon on an install that cannot succeed.

If you are only doing level 1 — which covers most integrations — you do not need any of this. Ask for the tv-api credential and start.

Once you have a token, the .npmrc setup (including the Docker build-secret pattern) is documented under Getting started → Install the SDK.

What to send us

One email gets an integration unblocked. Include:

1. Who: the organization, and the developer email(s) that will hold the credentials.
2. Which building(s): name or buildingId, and whether this is a sandbox or a production tenant.
3. What the integration does: push a data layer, stream telemetry, create tickets, receive webhooks — this decides the role.
4. Where it runs: for webhooks, the public https URL that will receive deliveries (it must resolve publicly — see Out of the twin).
5. Whether you need registry access for the SDK or the n8n nodes.

→ developers@tango.vision

Checking that it works

# 1. Is the API reachable at all? (no token needed)
curl -s https://tv-api.k8s.tangovision.dev/health

# 2. Does the token work, and can it see the building?
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://tv-api.k8s.tangovision.dev/api/v1/buildings/$BUILDING_ID/data-layers"

Read the codes literally, they are distinct on purpose:

• 401 — no token, an expired one, or one from the wrong realm.
• 403 — the token is valid, but it lacks the permission, lacks the org claim (No organization context), or the building belongs to another organization (Building does not belong to your organization).
• 404 — no building with that id exists at all. Usually a stale id in a config file.

The interactive API browser for the hosted environment is at /api-docs. It lists every path, including ones this section does not cover.