Reference
View as MarkdownPlatform API
13 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes
/platform-servicesPlatform services: the catalog and what is set up
Services NebulaCtrl runs for its own use (S3 storage, a log store, a tailnet control server, single sign-on), each wired into the integration that asked for it.
Response 200 · OK · application/json
- PlatformKindView[] | nullrequired
- projectIdstring
401Unauthorized403Forbidden500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-servicesSet up a platform service for me
Stages the service in the team's system project, deploys it, then wires it into the integration (a backup destination, a log drain, the Tailscale integration or a sign-in provider) with generated credentials and tests the connection. Returns 202; poll the service (or listen to events) until status is ready or failed. Not idempotent-keyed: the response of the identity provider carries a one-time password.
Request body · application/json · required
- bucketstringS3: the bucket (default nebulactrl-backups).
- hostnamestringPublic hostname; default a generated one under the server's base domain, else <ip>.sslip.io.
- kindenum: s3 | loki | grafana | headscale | idp | registryrequiredWhich platform service to set up. registry: the managed container registry for build servers.
- providerNamestringSingle sign-on: the label of the sign-in button (default NebulaCtrl SSO).
- publicUrlstringOverrides https://<hostname>: a proxy on a non-standard port, or plain http for a local test.
- replacebooleanHeadscale: replace an existing Tailscale integration.
- retentionDaysinteger (int64)Loki: how long logs are kept (default 14).
- serverIdstringThe server it runs on (Grafana always runs next to Loki).
- variantenum: pocketid | autheliaSingle sign-on: the product. pocketid (default): passkeys only, people managed in Pocket ID. authelia: password + 2FA, NebulaCtrl manages the people.
Response 202 · Accepted · application/json
- initialPasswordstringShown once; reset it from the people list if lost.
- initialUserstring
- PlatformServiceViewrequired
401Unauthorized403Forbidden409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}Get a platform service
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Response 200 · OK · application/json
- PlatformBackupView
- createdAtstring (date-time)required
- map of stringrequired
- environmentSlugstring
- hostnamestringrequired
- idstringrequired
- kindenum: s3 | loki | grafana | headscale | idp | registryrequired
- labelstringrequired
- messagestringrequiredWhat is happening or why it failed.
- projectIdstring
- publicUrlstringrequired
- serverIdstring
- serverNamestring
- PlatformServiceRef[] | nullrequired
- statusenum: provisioning | ready | failed | removingrequired
- stepenum: configure | deploy | await | wire | donerequired
- updatedAtstring (date-time)required
- PlatformUserView[] | null
- variantenum: pocketid | authelia
- warningsstring[] | nullrequired
- PlatformWiringView
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}Remove a platform service and unwire its integration
confirm must equal the kind. The integration is removed first; an integration still in use (a backup destination with schedules or stored backups, a tailnet in use, people who sign in only through the provider) answers 409 and nothing changes. deleteData also deletes the data volumes.
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
confirm | query | string | Must equal the kind. |
deleteData | query | boolean | Also delete the data volumes. |
force | query | boolean | Single sign-on: remove it although people can sign in only through it. |
Response 204 · No Content
No body.
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/admin-linkCreate a one-time sign-in link for the first administrator of Pocket ID (instance administrators)
Asks Pocket ID for a one-time access token for the administrator created at set-up and returns the link. The link works once and expires after an hour. It is shown once: it is never stored, logged or audited (the audit entry says who asked). Pocket ID has no passwords: the link signs the person in, and they register a passkey from their account page. Only for the Pocket ID variant of single sign-on.
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Response 200 · OK · application/json
- emailstringrequired
- expiresAtstring (date-time)required
- urlstringrequiredOpen it once to sign in to Pocket ID and register a passkey. Shown once: it is not stored.
- usernamestringrequired
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error502Bad Gateway
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/backupSchedule a daily volume backup of a platform service's data
Uses the volume backup feature (restic) with the chosen destination: daily at 03:17 UTC, 7 daily, 4 weekly and 3 monthly kept.
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body · application/json · required
- destinationIdstringrequired
Response 200 · OK · application/json
- PlatformBackupView
- createdAtstring (date-time)required
- map of stringrequired
- environmentSlugstring
- hostnamestringrequired
- idstringrequired
- kindenum: s3 | loki | grafana | headscale | idp | registryrequired
- labelstringrequired
- messagestringrequiredWhat is happening or why it failed.
- projectIdstring
- publicUrlstringrequired
- serverIdstring
- serverNamestring
- PlatformServiceRef[] | nullrequired
- statusenum: provisioning | ready | failed | removingrequired
- stepenum: configure | deploy | await | wire | donerequired
- updatedAtstring (date-time)required
- PlatformUserView[] | null
- variantenum: pocketid | authelia
- warningsstring[] | nullrequired
- PlatformWiringView
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/reconnectRun the wiring of a ready platform service again
Headscale mints a new API key and updates the Tailscale integration; the others re-create a missing destination or drain and test it again.
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Response 202 · Accepted · application/json
- PlatformBackupView
- createdAtstring (date-time)required
- map of stringrequired
- environmentSlugstring
- hostnamestringrequired
- idstringrequired
- kindenum: s3 | loki | grafana | headscale | idp | registryrequired
- labelstringrequired
- messagestringrequiredWhat is happening or why it failed.
- projectIdstring
- publicUrlstringrequired
- serverIdstring
- serverNamestring
- PlatformServiceRef[] | nullrequired
- statusenum: provisioning | ready | failed | removingrequired
- stepenum: configure | deploy | await | wire | donerequired
- updatedAtstring (date-time)required
- PlatformUserView[] | null
- variantenum: pocketid | authelia
- warningsstring[] | nullrequired
- PlatformWiringView
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/retryRetry a failed platform service
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Response 202 · Accepted · application/json
- PlatformBackupView
- createdAtstring (date-time)required
- map of stringrequired
- environmentSlugstring
- hostnamestringrequired
- idstringrequired
- kindenum: s3 | loki | grafana | headscale | idp | registryrequired
- labelstringrequired
- messagestringrequiredWhat is happening or why it failed.
- projectIdstring
- publicUrlstringrequired
- serverIdstring
- serverNamestring
- PlatformServiceRef[] | nullrequired
- statusenum: provisioning | ready | failed | removingrequired
- stepenum: configure | deploy | await | wire | donerequired
- updatedAtstring (date-time)required
- PlatformUserView[] | null
- variantenum: pocketid | authelia
- warningsstring[] | nullrequired
- PlatformWiringView
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/revealReveal the generated credentials of a platform service (audited)
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Response 200 · OK · application/json
- PlatformCredential[] | nullrequired
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/usersPeople of the single sign-on provider
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Response 200 · OK · application/json
- PlatformUserView[] | nullrequired
401Unauthorized403Forbidden404Not Found422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/usersAdd a person to the single sign-on provider (instance administrators)
Rewrites the users file in the service's configuration and deploys it. Without a password one is generated and returned once.
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request body · application/json · required
- displayNamestringrequired
- emailstringrequired
- passwordstringEmpty generates one (returned once).
- usernamestringrequired
Response 201 · Created · application/json
- applyingbooleanrequiredThe change is being deployed (the sign-in page restarts for a few seconds).
- generatedPasswordstringShown once.
- PlatformUserViewrequired
- warningstring
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/users/{username}Remove a person from the single sign-on provider (instance administrators)
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
usernamerequired | path | string |
Response 200 · OK · application/json
- applyingbooleanrequiredThe change is being deployed (the sign-in page restarts for a few seconds).
- generatedPasswordstringShown once.
- PlatformUserViewrequired
- warningstring
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.
/platform-services/{id}/users/{username}/reset-passwordSet a new password for a person (instance administrators)
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
usernamerequired | path | string |
Request body · application/json · required
- passwordstringEmpty generates one (returned once).
Response 200 · OK · application/json
- applyingbooleanrequiredThe change is being deployed (the sign-in page restarts for a few seconds).
- generatedPasswordstringShown once.
- PlatformUserViewrequired
- warningstring
401Unauthorized403Forbidden404Not Found409Conflict422Unprocessable Entity500Internal Server Error
Errors are RFC 9457 application/problem+json with a stable code field.