Copy-paste examples for the Partner API. Two complete walkthroughs, then one call per endpoint.

Copy-paste-Beispiele fuer die Partner API. Zwei komplette Walkthroughs, danach ein Aufruf je Endpunkt.

Set your key once

Key einmal setzen

Use a partner key (nsk_p_…) for everything, or a user key (nsk_u_…) for self-service on one account.

Nimm einen Partner-Key (nsk_p_…) fuer alles, oder einen User-Key (nsk_u_…) fuer Self-Service auf einem Konto.

export KEY='nsk_p_xxxxxxxxxxxxxxxx'
export BASE='https://ns.10be.de/partner/v1'

Walkthrough A: an instance managed for an end-user

Walkthrough A: eine Instanz fuer einen Endnutzer

The partner creates the end-user and the instance in one call, then hands the end-user their own key. Use this when each instance belongs to one of your customers.

Der Partner legt Endnutzer und Instanz in einem Aufruf an und gibt dem Endnutzer dann seinen eigenen Key. Dafuer, wenn jede Instanz einem deiner Kunden gehoert.

1. Create the instance and the end-user (by email). The reply holds, once: api_secret, a ready user_key, and the new user (uid, email, first password). Save them.
2. Anlegen: Instanz + Endnutzer (per email). Die Antwort enthaelt einmalig: api_secret, einen fertigen user_key und den neuen user (uid, email, erstes password). Speichern.

curl -fsS -X POST "$BASE/instances" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "email": "customer@example.org", "name": "my-cgm", "units": "mg/dl", "display": "My CGM" }'

{ "ok": true, "success": "ok", "id": 678, "name": "my-cgm", "status": "creating",
  "url": "https://my-cgm.10be.de/", "api_secret": "…once…", "user_key": "nsk_u_…once…",
  "billing_model": "partner", "user": { "uid": 12345, "email": "customer@example.org", "password": "…once…" } }

2. Hand the user_key to the customer's app. From then on the app uses that key for this customer (it is scoped to their instance).
3. Gib den user_key an die App des Kunden. Die App nutzt ab dann diesen Key fuer diesen Kunden (auf seine Instanz begrenzt).
4. Check when it is live (status running):
5. Pruefen, wann sie live ist (Status running):

curl -fsS "$BASE/instances/678" -H "Authorization: Bearer $KEY"

4. Change a setting any time (only the fields you send change):
5. Aendern jederzeit (nur die geschickten Felder aendern sich):

curl -fsS -X PATCH "$BASE/instances/678" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "display": "New title", "bghigh": 200 }'

The customer can also log in at the instance with the returned password, or your app drives everything with the user_key.

Der Kunde kann sich an der Instanz mit dem zurueckgegebenen Passwort einloggen, oder deine App steuert alles ueber den user_key.

Walkthrough B: an instance only you (the partner) manage

Walkthrough B: eine Instanz, die nur du (der Partner) verwaltest

Leave out both uid and email. The instance then belongs to your own partner account: there is no end-user and no user_key, and only your partner key controls it.

Lass uid UND email weg. Die Instanz gehoert dann deinem eigenen Partner-Konto: es gibt keinen Endnutzer und keinen user_key, und nur dein Partner-Key steuert sie.

1. Create with just a name (and optionally api_secret). The reply holds api_secret once; there is no user block and no user_key.
2. Anlegen nur mit name (optional api_secret). Die Antwort enthaelt api_secret einmalig; kein user-Block, kein user_key.

curl -fsS -X POST "$BASE/instances" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "internal-demo", "units": "mmol" }'

{ "ok": true, "success": "ok", "id": 679, "name": "internal-demo", "status": "creating",
  "url": "https://internal-demo.10be.de/", "api_secret": "…once…", "billing_model": "partner" }

2. Manage it with your partner key: read status, change settings, stop/start, delete.
3. Verwalten mit deinem Partner-Key: Status lesen, Einstellungen aendern, stop/start, loeschen.

curl -fsS "$BASE/instances/679" -H "Authorization: Bearer $KEY"

curl -fsS -X PATCH "$BASE/instances/679" \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "action": "stop" }'

{ "ok": true, "success": "ok" }

Reference: one call per endpoint

Referenz: ein Aufruf je Endpunkt

GET /instanceslist

curl -fsS "$BASE/instances" -H "Authorization: Bearer $KEY"

GET /instances/{id}

curl -fsS "$BASE/instances/678" -H "Authorization: Bearer $KEY"

PATCH (or PUT) /instances/{id}

PUT is accepted as an alias of PATCH (for clients that cannot send PATCH).

PUT wird als Alias von PATCH akzeptiert (fuer Clients, die kein PATCH koennen).

# change settings
curl -fsS -X PATCH "$BASE/instances/678" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "display": "New title", "bglow": 70 }'

# same via PUT
curl -fsS -X PUT "$BASE/instances/678" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "display": "New title" }'

# an action (stop | start | restart | redeploy | delete | rotate_secret | activate | deactivate)
curl -fsS -X PATCH "$BASE/instances/678" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "action": "rotate_secret" }'

# turn an instance off / on (owner-checked). active:0 = off, active:1 = on.
# "active" is the English name for the internal "aktiv"; both work.
curl -fsS -X PATCH "$BASE/instances/678" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "active": 0 }'

Custom domains

Eigene Domains

# list
curl -fsS "$BASE/instances/678/domains" -H "Authorization: Bearer $KEY"

# add (the reply gives the DNS record to set)
curl -fsS -X POST "$BASE/instances/678/domains" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "domain": "cgm.example.org" }'

# verify the DNS record now (domain id 9)
curl -fsS -X POST "$BASE/instances/678/domains/9/verify" -H "Authorization: Bearer $KEY"

# remove
curl -fsS -X DELETE "$BASE/instances/678/domains/9" -H "Authorization: Bearer $KEY"

Wildcard domain partner key

Wildcard-Domain Partner-Key

curl -fsS "$BASE/wildcard" -H "Authorization: Bearer $KEY"

curl -fsS -X POST "$BASE/wildcard" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "domain": "ns.example.net" }'

curl -fsS -X POST "$BASE/wildcard/verify" -H "Authorization: Bearer $KEY"

POST /user-keyspartner key

# for all of a user's instances
curl -fsS -X POST "$BASE/user-keys" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "uid": 12345, "label": "mobile app" }'

# tied to one instance only
curl -fsS -X POST "$BASE/user-keys" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "uid": 12345, "instance_id": 678 }'

# rename a user key (give it a friendly name), key id 42
curl -fsS -X PATCH "$BASE/user-keys/42" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "label": "User Manfred" }'