From 4fbf3e2e0e06ed73b5f551aefd81c08f994e49ea Mon Sep 17 00:00:00 2001 From: Fabiano Eger Date: Tue, 7 Apr 2026 15:33:04 -0300 Subject: [PATCH] docs(api): add network token creation and device creation endpoints Document the new POST /integration/network/token endpoint with privilege support and the POST /integration/network/device endpoint for network-level device provisioning. --- ...te-device-using-network.RequestSchema.json | 73 +++++++++++++++++++ ...eate-device-using-network.StatusCodes.json | 38 ++++++++++ docs/api/create-device-using-network.api.mdx | 45 ++++++++++++ .../create-network-token.RequestSchema.json | 54 ++++++++++++++ .../api/create-network-token.StatusCodes.json | 45 ++++++++++++ docs/api/create-network-token.api.mdx | 45 ++++++++++++ docs/api/sidebar/api-sidebar.ts | 12 +++ 7 files changed, 312 insertions(+) create mode 100644 docs/api/create-device-using-network.RequestSchema.json create mode 100644 docs/api/create-device-using-network.StatusCodes.json create mode 100644 docs/api/create-device-using-network.api.mdx create mode 100644 docs/api/create-network-token.RequestSchema.json create mode 100644 docs/api/create-network-token.StatusCodes.json create mode 100644 docs/api/create-network-token.api.mdx diff --git a/docs/api/create-device-using-network.RequestSchema.json b/docs/api/create-device-using-network.RequestSchema.json new file mode 100644 index 00000000..ba9b320e --- /dev/null +++ b/docs/api/create-device-using-network.RequestSchema.json @@ -0,0 +1,73 @@ +{ + "title": "Body", + "body": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["name", "type", "connector"], + "properties": { + "name": { + "type": "string", + "description": "Device name", + "example": "My Network Device" + }, + "type": { + "type": "string", + "enum": ["mutable", "immutable"], + "description": "Device type", + "example": "mutable" + }, + "connector": { + "type": "string", + "description": "Connector ID for the device", + "example": "5f5a8f3351d4db99c40dece5" + }, + "serie_number": { + "type": "string", + "description": "Serial number for the device (optional, only if required by the network)", + "example": "AB87392C17CA" + }, + "tags": { + "type": "array", + "description": "Device tags as key-value string pairs", + "items": { + "type": "object", + "properties": { + "key": { "type": "string", "example": "location" }, + "value": { "type": "string", "example": "warehouse-01" } + } + }, + "example": [ + { "key": "location", "value": "warehouse-01" }, + { "key": "type", "value": "sensor" } + ] + } + } + }, + "examples": { + "Create Mutable Device": { + "value": { + "name": "My Network Device", + "type": "mutable", + "connector": "5f5a8f3351d4db99c40dece5" + } + }, + "Create Device with Serial Number and Tags": { + "value": { + "name": "Warehouse Sensor", + "type": "mutable", + "connector": "5f5a8f3351d4db99c40dece5", + "serie_number": "AB87392C17CA", + "tags": [ + { "key": "location", "value": "warehouse-01" }, + { "key": "type", "value": "temperature" } + ] + } + } + } + } + } + } +} diff --git a/docs/api/create-device-using-network.StatusCodes.json b/docs/api/create-device-using-network.StatusCodes.json new file mode 100644 index 00000000..a4e2f62c --- /dev/null +++ b/docs/api/create-device-using-network.StatusCodes.json @@ -0,0 +1,38 @@ +{ + "responses": { + "201": { + "description": "Device created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "object", + "properties": { + "device_id": { "type": "string", "example": "5dcad1c216174c001ca23ab9" }, + "token": { "type": "string", "example": "5a16405f-b32c-4c91-ae39-cbb2caba18d8" } + } + }, + "status": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { + "description": "Authorization denied. The Network Token is missing, invalid, or does not have the createDevice privilege.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { "type": "boolean", "example": false }, + "message": { "type": "string", "example": "Authorization Denied" } + } + } + } + } + } + } +} diff --git a/docs/api/create-device-using-network.api.mdx b/docs/api/create-device-using-network.api.mdx new file mode 100644 index 00000000..21471aa8 --- /dev/null +++ b/docs/api/create-device-using-network.api.mdx @@ -0,0 +1,45 @@ +--- +id: create-device-using-network +title: "Create Device using Network" +description: "Create a new device using a Network Token with the createDevice privilege." +sidebar_label: "Create Device using Network" +hide_title: true +hide_table_of_contents: true +api: eJy1V11v2zYU/SsEX9YClm3ZUvzxUCBNhiEY2gaLiz0ERnFFXttsZFIlqTie4f8+kJRsKXE+tnV5iS1fXh6ee3ju1Y5aWBo6vaWf0W6UviMzdYeSvKu+RjneY/6ezjuUo2FaFFYoSaf0QiNYJEAkbgjHe8GQlEbIJQHSTrURdkXsCgnzSy5DbKHFvchxiV0yW2GdQZgqipNSctR+XaHVQuRI7AosURtp/FMZNunSDlUFanC4rjid0uY2Xx2iCg7tUI0/SjT2o+JbOt35r0Ijp1OrS+xQpqRFad1PUBS5YD5p77txJ95Rw1a4BvfJbgukU6qy78hslTckuqUS1kg7IcSnlMis0o7BQjukVqBxSXzgMZmxWsglfcxzRVeVFR9gXeQu/NP2QHMIoftq0xMpUZZrh21dWshyl0is689PKlvtWB3guGO9YN881av4L+pQcnVJFipUNFS7lT1dpDBeDIdpzBOeTSYs6XNkmLrtDGqB32S5zvANO96gFpCTEE7eKf8c8g5RMt8SsSB1tUi2bSrpfQvP+cfxaDgZXMSji3NPrb8mh71Ba9g+VywXS8CQO9xG95CXSAJUUoDQxrFvcW1OCamtkDvcnqzmAWSugkQdQL/Ry+Eb0LhSpcGoH9P9ft/47bba7ZjykPHRsnlzoYdZWcGnoI9ajtPdEVKQ+gnN1pJtKLOhrRdEse/U21ace5epSg+Sk1lVr8cY/qwPQ25QGqX/NYTHsmwrphbMP+PVU6vRFEqawO2gH7t/J2VWO6UpGUNjFmWeb+l/cLG2+DSaMrevx4W7/E3wl7WXcgY8ZoP4LB4lrN+PGQyGkE383XJ94pXlEJ8l/XQRZcMBixI2iSPA4SRiWTZgkEE85uMgaWPBls3LlSmVI8hmOmf3Nd3JKYbPS7tSWvzlqSMcpUD+86h9C8QF5Ab3HbpGY2D5ysVuw70McPf1CddoV8p1xkIZDwbsik5pT0iLy9A4e5UH9g7ObFDfow4KLnVOp3RlbWGmvR4UoluaCOOuhaXqCkX3nVMxWEabRszc5WSlFnbrk1ZOMAu1v503A24ckYGroPVo9kgiUIjf8akBn5NmfJgYhCGlFD9KJFaRrSp11X665DeUbnBwU4yXoGsI4O+SM2sfGtL9YkgBS3SzRmUjLVgdKtzmKwSOzlAeooZwMR4MkxQiPupDlOCAR9l4yKOU9f0PZ6OxvwP1vPXmg7aHrGdOWgV1ybk/Frk6ltyQD4ccH0IW49YtH5PimnYr2ZGF545/KUyRw/ZziGofrU3PgqfJBPggGsdDFiX87CzKFqNBlPbHmGaTMSxw6Oi5DjPg2+m5rofGl+hBaYU+DJgNQQgZAoAxVUpLDFor5NI0zt5G9JIEIE4RUoSI8wGPEnY2jMaTJI0mgyxNOCSj0QB8R3M+8sdxRP21zvB/NFAHeKE8k8J6mDNYqqsv5Pz6yvUo1CZQGXf73X7lfcCc9zmozkrWIBvY2u04vAocJ+9WeXZHI/2J7xFHLiw+2F6Rg/CDkXemXeV6t7Theq6YDYSe0HmHrpxNTm/pbpeBwa863+/d4x8lamddc9fBtfBsO9/q1FU/NvuLcLxoFmbouuE/6RnOOMMKdz8L+2LsvOHk119uZrRDs+pFZq24W6Nh415GYEOn1L8W+Xvum7l7tqM5yGXpuwkNOd3f3150wLI= +sidebar_class_name: "post api-method" +info_path: docs/api/tagoio-api +custom_edit_url: null +--- + +import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; +import ParamsDetails from "@theme/ParamsDetails"; +import RequestSchema from "@theme/RequestSchema"; +import StatusCodes from "@theme/StatusCodes"; +import OperationTabs from "@theme/OperationTabs"; +import TabItem from "@theme/TabItem"; +import Heading from "@theme/Heading"; +import Translate from "@docusaurus/Translate"; + + + + + +Create a new device using a Network Token. The token must have the `createDevice` privilege enabled. + +This endpoint allows network integrations to provision devices programmatically without requiring a Profile Token. The device is created under the profile that owns the network and is automatically associated with the network and connector specified in the request. + +To use this endpoint, first [create a Network Token](/docs/api/create-network-token) with the `createDevice` privilege set to `true`. + +:::info Authorization +This endpoint uses a **Network Token** for authentication (not a Profile Token). Pass the token in the `Authorization` header. +::: + + + Request + + + + + + + diff --git a/docs/api/create-network-token.RequestSchema.json b/docs/api/create-network-token.RequestSchema.json new file mode 100644 index 00000000..7fbe8efa --- /dev/null +++ b/docs/api/create-network-token.RequestSchema.json @@ -0,0 +1,54 @@ +{ + "title": "Body", + "body": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": ["name", "network"], + "properties": { + "name": { + "type": "string", + "description": "Display name for the token", + "example": "My Network Token" + }, + "network": { + "type": "string", + "description": "Network ID that this token will be associated with", + "example": "5dc1e879d344a330bb1548db" + }, + "privileges": { + "type": "object", + "description": "Optional privileges to grant to the token. Omit to create a token with default permissions (data ingestion only).", + "properties": { + "createDevice": { + "type": "boolean", + "description": "Allow the token to create devices via POST /integration/network/device", + "example": true + } + } + } + } + }, + "examples": { + "Basic Token": { + "value": { + "name": "Data Ingestion Token", + "network": "5dc1e879d344a330bb1548db" + } + }, + "Token with Device Creation Privilege": { + "value": { + "name": "Provisioning Token", + "network": "5dc1e879d344a330bb1548db", + "privileges": { + "createDevice": true + } + } + } + } + } + } + } +} diff --git a/docs/api/create-network-token.StatusCodes.json b/docs/api/create-network-token.StatusCodes.json new file mode 100644 index 00000000..d1180599 --- /dev/null +++ b/docs/api/create-network-token.StatusCodes.json @@ -0,0 +1,45 @@ +{ + "responses": { + "200": { + "description": "Network token created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "result": { + "type": "object", + "properties": { + "token": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, + "name": { "type": "string", "example": "My Network Token" }, + "network": { "type": "string", "example": "5dc1e879d344a330bb1548db" }, + "privileges": { + "type": "object", + "properties": { + "createDevice": { "type": "boolean", "example": true } + } + } + } + }, + "status": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { + "description": "Authorization denied. The Profile Token is missing, invalid, or does not have write permission.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { "type": "boolean", "example": false }, + "message": { "type": "string", "example": "Authorization Denied" } + } + } + } + } + } + } +} diff --git a/docs/api/create-network-token.api.mdx b/docs/api/create-network-token.api.mdx new file mode 100644 index 00000000..e68f63a9 --- /dev/null +++ b/docs/api/create-network-token.api.mdx @@ -0,0 +1,45 @@ +--- +id: create-network-token +title: "Create Network Token" +description: "Create a new token for a network integration with optional privileges." +sidebar_label: "Create Network Token" +hide_title: true +hide_table_of_contents: true +api: eJytV01v4zYQ/SvEXNoCli3bkr8OC2SbogiKboJuegp8GIljmRtZVEjKXtfwfy9IyrGUOB/bxpdY8vBx5s3Mm8keDOYa5nfwhcxWqnt2K++pZD83j2FBGyp+gUUAnHSmRGWELGEOvypCQwxZSVtm3JmlVO7Z44jSUK7QmrOtMCsm3VEsWKXERhSUk+5BALIib3XFYQ6Zg20ud65AAIoeatLms+Q7mO/do1DEYW5UTQFksjRUGvsTVlUhMgfX/6ato3vQ2YrWaL+ZXUUwB5l+o8w0uB7oDkpcEwTQeG/jrZR1zQjS9qz7/YShjRJlDk9ZuRS6KnDHrLXjw6zIswMB0HdcV4U9/eeOdeiGw+nmN+84nry6ZGaFhpmV0E0GtqIoWEoMtZaZQEPcUd+5O+HZgKaTGR/FMY5GUZoOknjKU+vDKTPn6Oq6cf08ncxIlissjf3SjrxLpc/xJW1E1qY0lbIgLJ9ddFEUcnuCs9wegXEHodlGILu5/nrL+q2i6zeE9r1VmwNbNgf7eXzn/PqMWmRNQuZ72GBR0yn1cIkG2VWZk3Y1fSzOx7y9wuwhgNsmQWbFfOTMdZBFujkSeO7WGyU3QgtZijL/kTufJrNL+iMD1jVFupKl9nbDKLJ/zpecT4CH4kzXWUZaL+ui2MH/aMNudSjSdWHetjPHPD3tllapJxFN4ygKaThLw3jA4xAng3EYx+NxksRxFEWRa70Xevs/N+xHdNsP9sy54tYGTa3faX4III4Gz3N/UZuVVOIfX6ucSkH847L9HheXWGg6BLAmrTF/I1Nddy+9u4+lviazknbOVFI7Z9CsYA5ndeMoXprUhpSdkXuoVQFzWBlT6Xm/j5Xo1TqkQc9gLntCwiE4Z0N1uG3ZLCxmVithdg70RsmlKKgRnrtF2+Cr5dFT5ZMf3j6pe6zEH7R7rpqsbe8nhdCsLsVDbZWU7WStGgXtsd+ptFPYznPf4+mOoetuKzvO1MP9pFmFOdnBfZTFtlsBCHv5ipCTggC+h61WoMFwFCcY8kmEYUxDHqbTEQ+TLHI/jCfTmW2L4+bx7kC7m8sLkTZGPXbhwmJXp4xr9ukR45NH8aPsKSl2oHfATiy8FH6zEHzxVt3QuvQseRLPkA/D6WCUhTEfj8N0ORmGSTSlJJ1NcUkjS09TLe+npzlwnJ7n6aHSCEWs8batghClN8Ask3VpmCZjRJnrVuxdj14rARwkhAlhyPmQh3E2HoXTWZyEs2GaxBzjyWSIblpaGfnrtPX9dkT4iGFsHVxKx5wwzq1bzOXVNbu4uYIAbK976ga9qBc1UoeZlTrrmlWONZYtX5pVuDsgnuRhfxLMj1udm8wb+m76VYHCjSUnP/tG2e6ghdXiJ2jG5yKAlVXC+R3s9ylq+lsVh4N9/VCTsvK0CGCDSmBqmbpbHIJjZq1y3dPOxuMjC2+tO8Fxg3k+Fqw4+hO2Byvzqu2iJdZ2t4MA0mb/X0tuzyjc2h0etzAH93+E62W3Qth3eyiwzGs3MMBj2s+/6LBqTA== +sidebar_class_name: "post api-method" +info_path: docs/api/tagoio-api +custom_edit_url: null +--- + +import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint"; +import ParamsDetails from "@theme/ParamsDetails"; +import RequestSchema from "@theme/RequestSchema"; +import StatusCodes from "@theme/StatusCodes"; +import OperationTabs from "@theme/OperationTabs"; +import TabItem from "@theme/TabItem"; +import Heading from "@theme/Heading"; +import Translate from "@docusaurus/Translate"; + + + + + +Create a new token for a network integration. Network Tokens are used to authenticate requests from external systems to TagoIO network endpoints (e.g., sending data, creating devices). + +Tokens can be granted optional **privileges** that control what operations the token is allowed to perform beyond the default data ingestion. Currently supported privileges: + +- **createDevice** – Allows the token to create devices via `POST /integration/network/device`. + +:::info Authorization +This endpoint requires a **Profile Token** with write permission. The profile must own the target network. +::: + + + Request + + + + + + + diff --git a/docs/api/sidebar/api-sidebar.ts b/docs/api/sidebar/api-sidebar.ts index f2cc2199..831a9996 100644 --- a/docs/api/sidebar/api-sidebar.ts +++ b/docs/api/sidebar/api-sidebar.ts @@ -97,6 +97,18 @@ const sidebar: SidebarsConfig = { label: "Send Data using Network", className: "api-method post", }, + { + type: "doc", + id: "api/create-network-token", + label: "Create Network Token", + className: "api-method post", + }, + { + type: "doc", + id: "api/create-device-using-network", + label: "Create Device using Network", + className: "api-method post", + }, ], }, {