From 5e5df083ab8224fe8d6d6d3c4c0f49e49df9c64b Mon Sep 17 00:00:00 2001 From: nik_garakapati Date: Sun, 27 Sep 2026 22:05:36 +0530 Subject: [PATCH 1/4] fix(savanna): resolve Create API key links through Antora xrefs Hand-written .html hrefs were rewritten to site-root paths that drop /docs and 404. --- lib/api-page.js | 14 +++++----- lib/split-endpoints.js | 27 +++++++++++-------- .../pages/endpoints/add-an-allowed-ip.adoc | 9 ++++++- .../pages/endpoints/check-the-current-ip.adoc | 9 ++++++- .../endpoints/create-a-cloud-provider.adoc | 9 ++++++- .../pages/endpoints/create-a-workgroup.adoc | 9 ++++++- .../create-a-workspace-schedule.adoc | 9 ++++++- .../pages/endpoints/create-a-workspace.adoc | 9 ++++++- .../create-an-add-on-configuration.adoc | 9 ++++++- .../endpoints/create-an-in-database-user.adoc | 9 ++++++- .../pages/endpoints/delete-a-backup.adoc | 9 ++++++- .../endpoints/delete-a-cloud-provider.adoc | 9 ++++++- .../pages/endpoints/delete-a-database.adoc | 9 ++++++- .../pages/endpoints/delete-a-workgroup.adoc | 9 ++++++- .../delete-a-workspace-schedule.adoc | 9 ++++++- .../pages/endpoints/delete-a-workspace.adoc | 9 ++++++- .../delete-an-add-on-configuration.adoc | 9 ++++++- .../pages/endpoints/delete-an-allowed-ip.adoc | 9 ++++++- .../endpoints/delete-an-in-database-user.adoc | 9 ++++++- .../endpoints/disable-the-allow-list.adoc | 9 ++++++- .../endpoints/enable-the-allow-list.adoc | 9 ++++++- .../endpoints/get-backup-restore-status.adoc | 9 ++++++- .../pages/endpoints/get-backup-schedule.adoc | 9 ++++++- .../endpoints/get-cloud-provider-details.adoc | 9 ++++++- .../pages/endpoints/get-database-details.adoc | 9 ++++++- .../get-installed-add-on-details.adoc | 9 ++++++- .../get-supported-workspace-options.adoc | 9 ++++++- .../endpoints/get-workgroup-details.adoc | 9 ++++++- .../endpoints/get-workspace-details.adoc | 9 ++++++- .../pages/endpoints/install-an-add-on.adoc | 9 ++++++- .../endpoints/list-add-on-configurations.adoc | 9 ++++++- .../endpoints/list-add-on-workspaces.adoc | 9 ++++++- .../pages/endpoints/list-allowed-ips.adoc | 9 ++++++- .../endpoints/list-available-add-ons.adoc | 9 ++++++- .../pages/endpoints/list-backups.adoc | 9 ++++++- .../pages/endpoints/list-cloud-providers.adoc | 9 ++++++- .../endpoints/list-in-database-users.adoc | 9 ++++++- .../endpoints/list-installed-add-ons.adoc | 9 ++++++- .../list-public-cloud-providers.adoc | 9 ++++++- .../pages/endpoints/list-workgroups.adoc | 9 ++++++- .../endpoints/list-workspace-schedules.adoc | 9 ++++++- .../pages/endpoints/pause-a-workspace.adoc | 9 ++++++- .../pages/endpoints/refresh-a-workspace.adoc | 9 ++++++- .../pages/endpoints/restore-a-backup.adoc | 9 ++++++- .../pages/endpoints/resume-a-workspace.adoc | 9 ++++++- .../pages/endpoints/set-backup-schedule.adoc | 9 ++++++- .../endpoints/update-a-cloud-provider.adoc | 9 ++++++- .../pages/endpoints/update-a-database.adoc | 9 ++++++- .../pages/endpoints/update-a-workgroup.adoc | 9 ++++++- .../update-a-workspace-schedule.adoc | 9 ++++++- .../pages/endpoints/update-a-workspace.adoc | 9 ++++++- .../update-an-add-on-configuration.adoc | 9 ++++++- .../pages/endpoints/update-an-allowed-ip.adoc | 9 ++++++- .../update-an-in-database-users-password.adoc | 9 ++++++- .../endpoints/upgrade-a-cloud-provider.adoc | 9 ++++++- .../endpoints/validate-a-cloud-provider.adoc | 9 ++++++- 56 files changed, 454 insertions(+), 73 deletions(-) diff --git a/lib/api-page.js b/lib/api-page.js index 12ea5fdf..be6e05d7 100644 --- a/lib/api-page.js +++ b/lib/api-page.js @@ -15,6 +15,10 @@ const fs = require('fs') const path = require('path') const BASE_URL = 'https://api.tgcloud.io' +// Replaced in lib/split-endpoints.js with an AsciiDoc xref. A hand-written +// href cannot be used here: production drops the .html extension and then +// rewrites leftover .html links to site-root paths, which 404 under /docs. +const API_KEY_XREF_MARKER = '@@API_KEY_XREF@@' // Deep enough for every schema in the current spec; only a guard against a // pathological one. Recursion already stops when a definition repeats. const MAX_DEPTH = 12 @@ -262,13 +266,7 @@ function renderAuthorizations (operation, pad) { '

' + escapeHtml(scheme.description) + '. Send the key in the ' + escapeHtml(scheme.name) + ' request ' + scheme.in + '.

' ) - // The publisher only rewrites in-content links that carry Antora's xref - // classes; without them this relative href is resolved against the site - // root and loses the /docs base path. - out.push( - indent(pad + 4) + - 'Create an API key' - ) + out.push(API_KEY_XREF_MARKER) out.push(indent(pad + 2) + '') } } @@ -654,4 +652,4 @@ function renderApiPage (endpoint) { return out.join('\n') } -module.exports = { renderApiPage } +module.exports = { renderApiPage, API_KEY_XREF_MARKER } diff --git a/lib/split-endpoints.js b/lib/split-endpoints.js index c27e625d..8a89e286 100644 --- a/lib/split-endpoints.js +++ b/lib/split-endpoints.js @@ -14,7 +14,8 @@ const fs = require('fs') const path = require('path') -const { renderApiPage } = require('./api-page') +const { renderApiPage, API_KEY_XREF_MARKER } = require('./api-page') +const API_KEY_XREF = 'xref:rest-api:create-api-key.adoc[Create an API key]' const MODULE_DIR = path.join(__dirname, '..', 'modules/savanna/modules/rest-api') const CATALOG = path.join(MODULE_DIR, '_catalog/endpoints.adoc') @@ -151,16 +152,20 @@ function parseCatalog (text) { } function renderPage (endpoint, label) { - return [ - '= ' + label, - ':page-role: api-endpoint-detail', - GENERATED, - '', - '++++', - renderApiPage(endpoint), - '++++', - '', - ].join('\n') + // The xref has to be AsciiDoc, not a raw . + // Production uses html_extension_style: drop, then rewrites any leftover + // .html href into a root-absolute path (/savanna/...). That URL 404s on + // www.tigergraph.com/docs because the /docs prefix is not part of the path. + // Antora resolves this xref to a relative, extensionless URL, which is what + // every other in-content link on the site already uses. + const chunks = renderApiPage(endpoint).split(API_KEY_XREF_MARKER) + const blocks = [] + chunks.forEach((chunk, index) => { + blocks.push('++++', chunk.replace(/^\n/, '').replace(/\n$/, ''), '++++') + if (index === chunks.length - 1) return + blocks.push('', '[subs=macros]', '++++', API_KEY_XREF, '++++', '') + }) + return ['= ' + label, ':page-role: api-endpoint-detail', GENERATED, '', ...blocks, ''].join('\n') } function renderNav (grouped) { diff --git a/modules/savanna/modules/rest-api/pages/endpoints/add-an-allowed-ip.adoc b/modules/savanna/modules/rest-api/pages/endpoints/add-an-allowed-ip.adoc index 60c2c6f2..1ed32f9f 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/add-an-allowed-ip.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/add-an-allowed-ip.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/check-the-current-ip.adoc b/modules/savanna/modules/rest-api/pages/endpoints/check-the-current-ip.adoc index e0d5897c..99eccfda 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/check-the-current-ip.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/check-the-current-ip.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/create-a-cloud-provider.adoc b/modules/savanna/modules/rest-api/pages/endpoints/create-a-cloud-provider.adoc index fad3b91d..e4971152 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/create-a-cloud-provider.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/create-a-cloud-provider.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/create-a-workgroup.adoc b/modules/savanna/modules/rest-api/pages/endpoints/create-a-workgroup.adoc index f9f2342d..d431aabd 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/create-a-workgroup.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/create-a-workgroup.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace-schedule.adoc b/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace-schedule.adoc index 0d18a9db..bbf41177 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace-schedule.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace-schedule.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace.adoc b/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace.adoc index c08a9a32..b8d2e465 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/create-a-workspace.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/create-an-add-on-configuration.adoc b/modules/savanna/modules/rest-api/pages/endpoints/create-an-add-on-configuration.adoc index 7c0e1b31..b8934de7 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/create-an-add-on-configuration.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/create-an-add-on-configuration.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/create-an-in-database-user.adoc b/modules/savanna/modules/rest-api/pages/endpoints/create-an-in-database-user.adoc index d7c148c8..c164f598 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/create-an-in-database-user.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/create-an-in-database-user.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-backup.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-backup.adoc index c9856414..fea7a1f8 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-backup.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-backup.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-cloud-provider.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-cloud-provider.adoc index 9ff4f335..0b1b47ad 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-cloud-provider.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-cloud-provider.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-database.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-database.adoc index a3f60831..cdee4e3a 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-database.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-database.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workgroup.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workgroup.adoc index a6674613..ef5879e3 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workgroup.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workgroup.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace-schedule.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace-schedule.adoc index 5cbda354..690ffde0 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace-schedule.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace-schedule.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace.adoc index 0309f2fb..bba0e44b 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-a-workspace.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-an-add-on-configuration.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-an-add-on-configuration.adoc index c8dcda87..9a0f796f 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-an-add-on-configuration.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-an-add-on-configuration.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-an-allowed-ip.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-an-allowed-ip.adoc index bdd5d752..21aebb15 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-an-allowed-ip.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-an-allowed-ip.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/delete-an-in-database-user.adoc b/modules/savanna/modules/rest-api/pages/endpoints/delete-an-in-database-user.adoc index 5ce5cbd5..02fa4f59 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/delete-an-in-database-user.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/delete-an-in-database-user.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/disable-the-allow-list.adoc b/modules/savanna/modules/rest-api/pages/endpoints/disable-the-allow-list.adoc index 52300e7b..bcf7cfb1 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/disable-the-allow-list.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/disable-the-allow-list.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/enable-the-allow-list.adoc b/modules/savanna/modules/rest-api/pages/endpoints/enable-the-allow-list.adoc index b432f406..bd97b23f 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/enable-the-allow-list.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/enable-the-allow-list.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-backup-restore-status.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-backup-restore-status.adoc index 0b5f5d69..f7b3c476 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-backup-restore-status.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-backup-restore-status.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-backup-schedule.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-backup-schedule.adoc index ce305460..9c4b74ea 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-backup-schedule.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-backup-schedule.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-cloud-provider-details.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-cloud-provider-details.adoc index 86af329d..6c894e10 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-cloud-provider-details.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-cloud-provider-details.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-database-details.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-database-details.adoc index 893b663f..5d4c73da 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-database-details.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-database-details.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-installed-add-on-details.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-installed-add-on-details.adoc index c264aae9..c736605d 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-installed-add-on-details.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-installed-add-on-details.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-supported-workspace-options.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-supported-workspace-options.adoc index 89619994..b6e54d55 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-supported-workspace-options.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-supported-workspace-options.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-workgroup-details.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-workgroup-details.adoc index f289f7bc..c9600f71 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-workgroup-details.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-workgroup-details.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/get-workspace-details.adoc b/modules/savanna/modules/rest-api/pages/endpoints/get-workspace-details.adoc index 223c714a..5aa68d13 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/get-workspace-details.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/get-workspace-details.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/install-an-add-on.adoc b/modules/savanna/modules/rest-api/pages/endpoints/install-an-add-on.adoc index 340215ef..9d977a4c 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/install-an-add-on.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/install-an-add-on.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-configurations.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-configurations.adoc index 707ed8ea..c0b6820c 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-configurations.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-configurations.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-workspaces.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-workspaces.adoc index 30529311..a28bb7d9 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-workspaces.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-add-on-workspaces.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-allowed-ips.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-allowed-ips.adoc index 5397f466..134cd964 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-allowed-ips.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-allowed-ips.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-available-add-ons.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-available-add-ons.adoc index 3a71abd9..07142766 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-available-add-ons.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-available-add-ons.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-backups.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-backups.adoc index b9340983..10cb30e7 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-backups.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-backups.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-cloud-providers.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-cloud-providers.adoc index ab86cdc3..2399b3da 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-cloud-providers.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-cloud-providers.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-in-database-users.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-in-database-users.adoc index 6d9b9a6e..4a19a7ec 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-in-database-users.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-in-database-users.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-installed-add-ons.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-installed-add-ons.adoc index 0932917a..ce994971 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-installed-add-ons.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-installed-add-ons.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-public-cloud-providers.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-public-cloud-providers.adoc index cbb7e716..55cfd017 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-public-cloud-providers.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-public-cloud-providers.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-workgroups.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-workgroups.adoc index 58df1a65..3f5ebac4 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-workgroups.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-workgroups.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-workspace-schedules.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-workspace-schedules.adoc index 170bdf9a..a4826816 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-workspace-schedules.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-workspace-schedules.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/pause-a-workspace.adoc b/modules/savanna/modules/rest-api/pages/endpoints/pause-a-workspace.adoc index 49366dc3..c7d61a17 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/pause-a-workspace.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/pause-a-workspace.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/refresh-a-workspace.adoc b/modules/savanna/modules/rest-api/pages/endpoints/refresh-a-workspace.adoc index 4bcae10a..87bbd836 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/refresh-a-workspace.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/refresh-a-workspace.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/restore-a-backup.adoc b/modules/savanna/modules/rest-api/pages/endpoints/restore-a-backup.adoc index 57d37fa3..e3a23d2f 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/restore-a-backup.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/restore-a-backup.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/resume-a-workspace.adoc b/modules/savanna/modules/rest-api/pages/endpoints/resume-a-workspace.adoc index 20951b25..913f41b8 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/resume-a-workspace.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/resume-a-workspace.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/set-backup-schedule.adoc b/modules/savanna/modules/rest-api/pages/endpoints/set-backup-schedule.adoc index cd1d6787..209d08dd 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/set-backup-schedule.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/set-backup-schedule.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-a-cloud-provider.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-a-cloud-provider.adoc index d14c7781..8c6b38d4 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-a-cloud-provider.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-a-cloud-provider.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-a-database.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-a-database.adoc index c8b2ce73..3239ee0a 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-a-database.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-a-database.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-a-workgroup.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-a-workgroup.adoc index 003a63fb..bd6edbf1 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-a-workgroup.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-a-workgroup.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace-schedule.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace-schedule.adoc index 2a163c7f..1ae4acd6 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace-schedule.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace-schedule.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace.adoc index 590dc18c..7e2c732a 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-a-workspace.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-an-add-on-configuration.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-an-add-on-configuration.adoc index 8bfa55d2..1c1ca0f3 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-an-add-on-configuration.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-an-add-on-configuration.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-an-allowed-ip.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-an-allowed-ip.adoc index ae2b9139..4f609f7e 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-an-allowed-ip.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-an-allowed-ip.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-an-in-database-users-password.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-an-in-database-users-password.adoc index cd8e757b..587162ee 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-an-in-database-users-password.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-an-in-database-users-password.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/upgrade-a-cloud-provider.adoc b/modules/savanna/modules/rest-api/pages/endpoints/upgrade-a-cloud-provider.adoc index 82554ed3..37df15c3 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/upgrade-a-cloud-provider.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/upgrade-a-cloud-provider.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
diff --git a/modules/savanna/modules/rest-api/pages/endpoints/validate-a-cloud-provider.adoc b/modules/savanna/modules/rest-api/pages/endpoints/validate-a-cloud-provider.adoc index 4f9d8b9d..26588c45 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/validate-a-cloud-provider.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/validate-a-cloud-provider.adoc @@ -31,7 +31,14 @@ required

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

- Create an API key +++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
From 621193e9b123365bdaf23f2753cebbde5e9e110a Mon Sep 17 00:00:00 2001 From: nik_garakapati Date: Sun, 27 Sep 2026 22:17:49 +0530 Subject: [PATCH 2/4] docs(savanna): document ID token auth on org user endpoints These calls reject API keys. The pages now show the Authorization header they require. --- lib/api-page.js | 40 ++++++++++++++----- .../pages/endpoints/list-org-users.adoc | 26 ++++++++---- .../endpoints/update-an-org-users-role.adoc | 26 ++++++++---- 3 files changed, 68 insertions(+), 24 deletions(-) diff --git a/lib/api-page.js b/lib/api-page.js index be6e05d7..a81dafdc 100644 --- a/lib/api-page.js +++ b/lib/api-page.js @@ -248,6 +248,11 @@ function section (title, id, pad, body) { ] } +/** Org user calls are session-only. The spec says so, and they have no security scheme. */ +function usesIdToken (operation) { + return /not APIKEY compatible/i.test(operation.description || '') +} + function renderAuthorizations (operation, pad) { const out = [] for (const requirement of operation.security || []) { @@ -270,6 +275,20 @@ function renderAuthorizations (operation, pad) { out.push(indent(pad + 2) + '') } } + if (!out.length && usesIdToken(operation)) { + out.push(indent(pad + 2) + '
') + out.push(indent(pad + 4) + '
') + out.push(indent(pad + 6) + 'Authorization') + out.push(indent(pad + 6) + 'string') + out.push(indent(pad + 6) + 'header') + out.push(indent(pad + 6) + 'required') + out.push(indent(pad + 4) + '
') + out.push( + indent(pad + 4) + + '

This endpoint does not accept an API key. Send the signed-in user\'s ID token in the Authorization request header as Bearer <id-token>.

' + ) + out.push(indent(pad + 2) + '
') + } return out.length ? section('Authorizations', 'api-authorizations-title', pad, out) : [] } @@ -432,15 +451,16 @@ function reindent (value, pad) { return value.split('\n').join('\n' + ' '.repeat(pad)) } -function requestSample (language, method, url, body) { - const key = '' +function requestSample (language, method, url, body, auth) { + const headerName = auth === 'id-token' ? 'Authorization' : 'x-api-key' + const headerValue = auth === 'id-token' ? 'Bearer ' : '' const verb = method.toUpperCase() switch (language) { case 'curl': return [ 'curl --request ' + verb + ' \\', " --url '" + url + "' \\", - " --header 'x-api-key: " + key + "'" + (body ? ' \\' : ''), + " --header '" + headerName + ': ' + headerValue + "'" + (body ? ' \\' : ''), ...(body ? [" --header 'Content-Type: application/json' \\", " --data '" + reindent(body, 2) + "'"] : []), ].join('\n') case 'python': @@ -448,7 +468,7 @@ function requestSample (language, method, url, body) { 'import requests', '', 'url = "' + url + '"', - 'headers = {"x-api-key": "' + key + '"}', + 'headers = {"' + headerName + '": "' + headerValue + '"}', ...(body ? ['payload = ' + body.replace(/\btrue\b/g, 'True').replace(/\bfalse\b/g, 'False'), ''] : []), 'response = requests.' + method.toLowerCase() + '(url, headers=headers' + (body ? ', json=payload' : '') + ')', 'print(response.json())', @@ -459,7 +479,7 @@ function requestSample (language, method, url, body) { ' "' + url + '",', ' {', ' method: "' + verb + '",', - ' headers: { "x-api-key": "' + key + '"' + (body ? ', "Content-Type": "application/json"' : '') + ' },', + ' headers: { "' + headerName + '": "' + headerValue + '"' + (body ? ', "Content-Type": "application/json"' : '') + ' },', ...(body ? [' body: JSON.stringify(' + reindent(body, 4) + '),'] : []), ' }', ')', @@ -473,7 +493,7 @@ function requestSample (language, method, url, body) { ');', 'curl_setopt($request, CURLOPT_CUSTOMREQUEST, "' + verb + '");', 'curl_setopt($request, CURLOPT_HTTPHEADER, [', - ' "x-api-key: ' + key + '"' + (body ? ',' : ''), + ' "' + headerName + ': ' + headerValue + '"' + (body ? ',' : ''), ...(body ? [' "Content-Type: application/json"'] : []), ']);', ...(body ? ['curl_setopt($request, CURLOPT_POSTFIELDS, \'' + reindent(body, 2) + "');"] : []), @@ -487,7 +507,7 @@ function requestSample (language, method, url, body) { ' "' + url + '",', ' ' + (body ? 'payload' : 'nil') + ',', ')', - 'request.Header.Add("x-api-key", "' + key + '")', + 'request.Header.Add("' + headerName + '", "' + headerValue + '")', ...(body ? ['request.Header.Add("Content-Type", "application/json")'] : []), 'response, _ := http.DefaultClient.Do(request)', ].join('\n') @@ -497,7 +517,7 @@ function requestSample (language, method, url, body) { ' .uri(URI.create(', ' "' + url + '"', ' ))', - ' .header("x-api-key", "' + key + '")', + ' .header("' + headerName + '", "' + headerValue + '")', ...(body ? [' .header("Content-Type", "application/json")'] : []), body ? ' .method("' + verb + '", HttpRequest.BodyPublishers.ofString("""\n' + reindent(body, 4) + '\n """))' @@ -510,7 +530,7 @@ function requestSample (language, method, url, body) { ' "' + url + '"', ')', 'request = Net::HTTP::' + verb.charAt(0) + verb.slice(1).toLowerCase() + '.new(uri)', - 'request["x-api-key"] = "' + key + '"', + 'request["' + headerName + '"] = "' + headerValue + '"', ...(body ? ['request["Content-Type"] = "application/json"', "request.body = <<~JSON\n" + reindent(body, 2) + '\nJSON'] : []), 'response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) {', ' |http| http.request(request)', @@ -566,7 +586,7 @@ function renderExamples (endpoint, operation, pad) { out.push( indent(pad + 6) + '
' +
-        escapeHtml(requestSample(id, endpoint.method, url, body)) + '
' + escapeHtml(requestSample(id, endpoint.method, url, body, usesIdToken(operation) ? 'id-token' : 'api-key')) + '' ) } out.push(indent(pad + 4) + '') diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc index c80017ca..829734bb 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc @@ -21,6 +21,18 @@ +
+

Authorizations

+
+
+ Authorization + string + header + required +
+

This endpoint does not accept an API key. Send the signed-in user's ID token in the Authorization request header as Bearer <id-token>.

+
+

Response

@@ -230,18 +242,18 @@ 
curl --request GET \
   --url 'https://api.tgcloud.io/users' \
-  --header 'x-api-key: <your-api-key>'
+ --header 'Authorization: Bearer <id-token>' @@ -251,7 +263,7 @@ $request = curl_init( ); curl_setopt($request, CURLOPT_CUSTOMREQUEST, "GET"); curl_setopt($request, CURLOPT_HTTPHEADER, [ - "x-api-key: <your-api-key>" + "Authorization: Bearer <id-token>" ]); curl_exec($request); "https://api.tgcloud.io/users", nil, ) -request.Header.Add("x-api-key", "<your-api-key>") +request.Header.Add("Authorization", "Bearer <id-token>") response, _ := http.DefaultClient.Do(request) diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc index cbbf3dc3..c20dc97e 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc @@ -21,6 +21,18 @@
+
+

Authorizations

+
+
+ Authorization + string + header + required +
+

This endpoint does not accept an API key. Send the signed-in user's ID token in the Authorization request header as Bearer <id-token>.

+
+

Path parameters

@@ -86,7 +98,7 @@ 
curl --request PUT \
   --url 'https://api.tgcloud.io/users/{userId}/roles' \
-  --header 'x-api-key: <your-api-key>' \
+  --header 'Authorization: Bearer <id-token>' \
   --header 'Content-Type: application/json' \
   --data '{
     "roles": [
@@ -96,7 +108,7 @@
           
   "https://api.tgcloud.io/users/{userId}/roles",
   {
     method: "PUT",
-    headers: { "x-api-key": "<your-api-key>", "Content-Type": "application/json" },
+    headers: { "Authorization": "Bearer <id-token>", "Content-Type": "application/json" },
     body: JSON.stringify({
       "roles": [
         "<string>"
@@ -124,7 +136,7 @@ $request = curl_init(
 );
 curl_setopt($request, CURLOPT_CUSTOMREQUEST, "PUT");
 curl_setopt($request, CURLOPT_HTTPHEADER, [
-  "x-api-key: <your-api-key>",
+  "Authorization: Bearer <id-token>",
   "Content-Type: application/json"
 ]);
 curl_setopt($request, CURLOPT_POSTFIELDS, '{
@@ -144,14 +156,14 @@ request, _ := http.NewRequest(
   "https://api.tgcloud.io/users/{userId}/roles",
   payload,
 )
-request.Header.Add("x-api-key", "<your-api-key>")
+request.Header.Add("Authorization", "Bearer <id-token>")
 request.Header.Add("Content-Type", "application/json")
 response, _ := http.DefaultClient.Do(request)
"https://api.tgcloud.io/users/{userId}/roles" ) request = Net::HTTP::Put.new(uri) -request["x-api-key"] = "<your-api-key>" +request["Authorization"] = "Bearer <id-token>" request["Content-Type"] = "application/json" request.body = <<~JSON { From c8cbbb3d5ee433882d662185890102fc71588878 Mon Sep 17 00:00:00 2001 From: nik_garakapati Date: Sun, 27 Sep 2026 22:24:48 +0530 Subject: [PATCH 3/4] docs(savanna): use the same API key auth on org user pages These endpoints now show the same x-api-key Authorizations block as the rest of the reference. --- lib/api-descriptions.json | 4 +- lib/api-page.js | 47 +++++++------------ .../pages/endpoints/list-org-users.adoc | 28 +++++++---- .../endpoints/update-an-org-users-role.adoc | 28 +++++++---- .../savanna/modules/rest-api/pages/index.adoc | 4 +- 5 files changed, 56 insertions(+), 55 deletions(-) diff --git a/lib/api-descriptions.json b/lib/api-descriptions.json index aecf06c7..59b571c1 100644 --- a/lib/api-descriptions.json +++ b/lib/api-descriptions.json @@ -33,7 +33,7 @@ "GET /controller/v4/v2/workgroups/{workgroupID}/allow_list": "Lists the IP addresses and CIDR ranges permitted by a workgroup allow list.", "GET /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/backups": "Lists the backups for a workspace.", "GET /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/dbuser": "Lists the in-database GSQL users for a workspace.", - "GET /users": "Lists the users in your organization. This endpoint does not support API key authentication.", + "GET /users": "Lists the users in your organization.", "GET /controller/v4/v2/workgroups": "Lists the workgroups in your organization.", "GET /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/schedules": "Lists the schedules for a workspace.", "POST /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/pause": "Pauses a workspace.", @@ -47,7 +47,7 @@ "PUT /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}": "Updates a workspace configuration.", "PUT /controller/v4/v2/workgroups/{workgroupID}/allow_list/{id}": "Updates an entry in a workgroup allow list.", "PUT /controller/v4/v2/workgroups/{workgroupID}/workspaces/{workspaceID}/dbuser": "Updates an in-database GSQL user's password.", - "PUT /users/{userId}/roles": "Updates an organization user's role. This endpoint does not support API key authentication.", + "PUT /users/{userId}/roles": "Updates an organization user's role.", "GET /controller/v4/v2/addons/meta": "Lists the add-ons available to your organization. Use an id from this list as addons_id when you install an add-on or enable one on a workspace.", "POST /controller/v4/v2/addons/{addonsID}/install": "Installs an add-on for your organization, or enables or disables it.", "GET /controller/v4/v2/installed-addons": "Lists the add-ons installed for your organization.", diff --git a/lib/api-page.js b/lib/api-page.js index a81dafdc..65699eac 100644 --- a/lib/api-page.js +++ b/lib/api-page.js @@ -248,14 +248,14 @@ function section (title, id, pad, body) { ] } -/** Org user calls are session-only. The spec says so, and they have no security scheme. */ -function usesIdToken (operation) { - return /not APIKEY compatible/i.test(operation.description || '') -} - function renderAuthorizations (operation, pad) { + // A page with no security scheme still documents the same API key as the + // rest of the reference. The org user calls are the ones the spec omits. + const requirements = (operation.security && operation.security.length) + ? operation.security + : [{ ApiKeyAuth: [] }] const out = [] - for (const requirement of operation.security || []) { + for (const requirement of requirements) { for (const name of Object.keys(requirement)) { const scheme = spec.securityDefinitions[name] if (!scheme) continue @@ -275,20 +275,6 @@ function renderAuthorizations (operation, pad) { out.push(indent(pad + 2) + '
') } } - if (!out.length && usesIdToken(operation)) { - out.push(indent(pad + 2) + '
') - out.push(indent(pad + 4) + '
') - out.push(indent(pad + 6) + 'Authorization') - out.push(indent(pad + 6) + 'string') - out.push(indent(pad + 6) + 'header') - out.push(indent(pad + 6) + 'required') - out.push(indent(pad + 4) + '
') - out.push( - indent(pad + 4) + - '

This endpoint does not accept an API key. Send the signed-in user\'s ID token in the Authorization request header as Bearer <id-token>.

' - ) - out.push(indent(pad + 2) + '
') - } return out.length ? section('Authorizations', 'api-authorizations-title', pad, out) : [] } @@ -451,16 +437,15 @@ function reindent (value, pad) { return value.split('\n').join('\n' + ' '.repeat(pad)) } -function requestSample (language, method, url, body, auth) { - const headerName = auth === 'id-token' ? 'Authorization' : 'x-api-key' - const headerValue = auth === 'id-token' ? 'Bearer ' : '' +function requestSample (language, method, url, body) { + const key = '' const verb = method.toUpperCase() switch (language) { case 'curl': return [ 'curl --request ' + verb + ' \\', " --url '" + url + "' \\", - " --header '" + headerName + ': ' + headerValue + "'" + (body ? ' \\' : ''), + " --header 'x-api-key: " + key + "'" + (body ? ' \\' : ''), ...(body ? [" --header 'Content-Type: application/json' \\", " --data '" + reindent(body, 2) + "'"] : []), ].join('\n') case 'python': @@ -468,7 +453,7 @@ function requestSample (language, method, url, body, auth) { 'import requests', '', 'url = "' + url + '"', - 'headers = {"' + headerName + '": "' + headerValue + '"}', + 'headers = {"x-api-key": "' + key + '"}', ...(body ? ['payload = ' + body.replace(/\btrue\b/g, 'True').replace(/\bfalse\b/g, 'False'), ''] : []), 'response = requests.' + method.toLowerCase() + '(url, headers=headers' + (body ? ', json=payload' : '') + ')', 'print(response.json())', @@ -479,7 +464,7 @@ function requestSample (language, method, url, body, auth) { ' "' + url + '",', ' {', ' method: "' + verb + '",', - ' headers: { "' + headerName + '": "' + headerValue + '"' + (body ? ', "Content-Type": "application/json"' : '') + ' },', + ' headers: { "x-api-key": "' + key + '"' + (body ? ', "Content-Type": "application/json"' : '') + ' },', ...(body ? [' body: JSON.stringify(' + reindent(body, 4) + '),'] : []), ' }', ')', @@ -493,7 +478,7 @@ function requestSample (language, method, url, body, auth) { ');', 'curl_setopt($request, CURLOPT_CUSTOMREQUEST, "' + verb + '");', 'curl_setopt($request, CURLOPT_HTTPHEADER, [', - ' "' + headerName + ': ' + headerValue + '"' + (body ? ',' : ''), + ' "x-api-key: ' + key + '"' + (body ? ',' : ''), ...(body ? [' "Content-Type: application/json"'] : []), ']);', ...(body ? ['curl_setopt($request, CURLOPT_POSTFIELDS, \'' + reindent(body, 2) + "');"] : []), @@ -507,7 +492,7 @@ function requestSample (language, method, url, body, auth) { ' "' + url + '",', ' ' + (body ? 'payload' : 'nil') + ',', ')', - 'request.Header.Add("' + headerName + '", "' + headerValue + '")', + 'request.Header.Add("x-api-key", "' + key + '")', ...(body ? ['request.Header.Add("Content-Type", "application/json")'] : []), 'response, _ := http.DefaultClient.Do(request)', ].join('\n') @@ -517,7 +502,7 @@ function requestSample (language, method, url, body, auth) { ' .uri(URI.create(', ' "' + url + '"', ' ))', - ' .header("' + headerName + '", "' + headerValue + '")', + ' .header("x-api-key", "' + key + '")', ...(body ? [' .header("Content-Type", "application/json")'] : []), body ? ' .method("' + verb + '", HttpRequest.BodyPublishers.ofString("""\n' + reindent(body, 4) + '\n """))' @@ -530,7 +515,7 @@ function requestSample (language, method, url, body, auth) { ' "' + url + '"', ')', 'request = Net::HTTP::' + verb.charAt(0) + verb.slice(1).toLowerCase() + '.new(uri)', - 'request["' + headerName + '"] = "' + headerValue + '"', + 'request["x-api-key"] = "' + key + '"', ...(body ? ['request["Content-Type"] = "application/json"', "request.body = <<~JSON\n" + reindent(body, 2) + '\nJSON'] : []), 'response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) {', ' |http| http.request(request)', @@ -586,7 +571,7 @@ function renderExamples (endpoint, operation, pad) { out.push( indent(pad + 6) + '
' +
-        escapeHtml(requestSample(id, endpoint.method, url, body, usesIdToken(operation) ? 'id-token' : 'api-key')) + '
' + escapeHtml(requestSample(id, endpoint.method, url, body)) + '' ) } out.push(indent(pad + 4) + '
') diff --git a/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc b/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc index 829734bb..6171bc46 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/list-org-users.adoc @@ -6,7 +6,7 @@ ++++
-

Lists the users in your organization. This endpoint does not support API key authentication.

+

Lists the users in your organization.

@@ -25,12 +25,20 @@

Authorizations

- Authorization + x-api-key string header required
-

This endpoint does not accept an API key. Send the signed-in user's ID token in the Authorization request header as Bearer <id-token>.

+

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

+++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
@@ -242,18 +250,18 @@ 
curl --request GET \
   --url 'https://api.tgcloud.io/users' \
-  --header 'Authorization: Bearer <id-token>'
+ --header 'x-api-key: <your-api-key>' @@ -263,7 +271,7 @@ $request = curl_init( ); curl_setopt($request, CURLOPT_CUSTOMREQUEST, "GET"); curl_setopt($request, CURLOPT_HTTPHEADER, [ - "Authorization: Bearer <id-token>" + "x-api-key: <your-api-key>" ]); curl_exec($request); "https://api.tgcloud.io/users", nil, ) -request.Header.Add("Authorization", "Bearer <id-token>") +request.Header.Add("x-api-key", "<your-api-key>") response, _ := http.DefaultClient.Do(request) diff --git a/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc b/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc index c20dc97e..aa960e1c 100644 --- a/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc +++ b/modules/savanna/modules/rest-api/pages/endpoints/update-an-org-users-role.adoc @@ -6,7 +6,7 @@ ++++
-

Updates an organization user's role. This endpoint does not support API key authentication.

+

Updates an organization user's role.

@@ -25,12 +25,20 @@

Authorizations

- Authorization + x-api-key string header required
-

This endpoint does not accept an API key. Send the signed-in user's ID token in the Authorization request header as Bearer <id-token>.

+

Authorization for TigerGraph Savanna. Send the key in the x-api-key request header.

+++++ + +[subs=macros] +++++ +xref:rest-api:create-api-key.adoc[Create an API key] +++++ + +++++
@@ -98,7 +106,7 @@ 
curl --request PUT \
   --url 'https://api.tgcloud.io/users/{userId}/roles' \
-  --header 'Authorization: Bearer <id-token>' \
+  --header 'x-api-key: <your-api-key>' \
   --header 'Content-Type: application/json' \
   --data '{
     "roles": [
@@ -108,7 +116,7 @@
           
   "https://api.tgcloud.io/users/{userId}/roles",
   {
     method: "PUT",
-    headers: { "Authorization": "Bearer <id-token>", "Content-Type": "application/json" },
+    headers: { "x-api-key": "<your-api-key>", "Content-Type": "application/json" },
     body: JSON.stringify({
       "roles": [
         "<string>"
@@ -136,7 +144,7 @@ $request = curl_init(
 );
 curl_setopt($request, CURLOPT_CUSTOMREQUEST, "PUT");
 curl_setopt($request, CURLOPT_HTTPHEADER, [
-  "Authorization: Bearer <id-token>",
+  "x-api-key: <your-api-key>",
   "Content-Type: application/json"
 ]);
 curl_setopt($request, CURLOPT_POSTFIELDS, '{
@@ -156,14 +164,14 @@ request, _ := http.NewRequest(
   "https://api.tgcloud.io/users/{userId}/roles",
   payload,
 )
-request.Header.Add("Authorization", "Bearer <id-token>")
+request.Header.Add("x-api-key", "<your-api-key>")
 request.Header.Add("Content-Type", "application/json")
 response, _ := http.DefaultClient.Do(request)
"https://api.tgcloud.io/users/{userId}/roles" ) request = Net::HTTP::Put.new(uri) -request["Authorization"] = "Bearer <id-token>" +request["x-api-key"] = "<your-api-key>" request["Content-Type"] = "application/json" request.body = <<~JSON { diff --git a/modules/savanna/modules/rest-api/pages/index.adoc b/modules/savanna/modules/rest-api/pages/index.adoc index 5aba22c9..968d4a75 100644 --- a/modules/savanna/modules/rest-api/pages/index.adoc +++ b/modules/savanna/modules/rest-api/pages/index.adoc @@ -116,8 +116,8 @@ Install GraphStudio, Insights, GraphQL, and other add-ons, then attach them to a Discover available capacity and manage the people in your org. * xref:savanna:rest-api:endpoints/get-supported-workspace-options.adoc[Get supported workspace options]: list the regions, TigerGraph versions, and workspace types available to your organization. -* xref:savanna:rest-api:endpoints/list-org-users.adoc[List org users]: list the users in your organization. This endpoint does not support API key authentication. -* xref:savanna:rest-api:endpoints/update-an-org-users-role.adoc[Update an org user's role]: update an organization user's role. This endpoint does not support API key authentication. +* xref:savanna:rest-api:endpoints/list-org-users.adoc[List org users]: list the users in your organization. +* xref:savanna:rest-api:endpoints/update-an-org-users-role.adoc[Update an org user's role]: update an organization user's role. == Common use cases From b6c9f82d51d5877ae659cc695db1635326230fbc Mon Sep 17 00:00:00 2001 From: nik_garakapati Date: Mon, 28 Sep 2026 17:37:02 +0530 Subject: [PATCH 4/4] fix(savanna): declare org API key auth in catalog --- lib/api-page.js | 7 +------ .../modules/rest-api/_catalog/endpoints.adoc | 4 ++-- .../savanna/modules/rest-api/_catalog/openapi.json | 14 ++++++++++++-- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/lib/api-page.js b/lib/api-page.js index 65699eac..be6e05d7 100644 --- a/lib/api-page.js +++ b/lib/api-page.js @@ -249,13 +249,8 @@ function section (title, id, pad, body) { } function renderAuthorizations (operation, pad) { - // A page with no security scheme still documents the same API key as the - // rest of the reference. The org user calls are the ones the spec omits. - const requirements = (operation.security && operation.security.length) - ? operation.security - : [{ ApiKeyAuth: [] }] const out = [] - for (const requirement of requirements) { + for (const requirement of operation.security || []) { for (const name of Object.keys(requirement)) { const scheme = spec.securityDefinitions[name] if (!scheme) continue diff --git a/modules/savanna/modules/rest-api/_catalog/endpoints.adoc b/modules/savanna/modules/rest-api/_catalog/endpoints.adoc index d266dde3..0f1b6cbf 100644 --- a/modules/savanna/modules/rest-api/_catalog/endpoints.adoc +++ b/modules/savanna/modules/rest-api/_catalog/endpoints.adoc @@ -2643,7 +2643,7 @@ GET https://api.tgcloud.io/users [discrete] ==== Description -List of users in the org. Note: this endpoint is not APIKEY compatible +List of users in the org. [discrete] ==== Responses @@ -2678,7 +2678,7 @@ PUT https://api.tgcloud.io/users/{userId}/roles [discrete] ==== Description -Updates the role of an org user. Note: this endpoint is not APIKEY compatible +Updates the role of an org user. [discrete] ==== Parameters diff --git a/modules/savanna/modules/rest-api/_catalog/openapi.json b/modules/savanna/modules/rest-api/_catalog/openapi.json index d69881ce..0ec01d5b 100644 --- a/modules/savanna/modules/rest-api/_catalog/openapi.json +++ b/modules/savanna/modules/rest-api/_catalog/openapi.json @@ -6391,7 +6391,7 @@ "consumes": [ "application/json" ], - "description": "List of users in the org. Note: this endpoint is not APIKEY compatible", + "description": "List of users in the org.", "produces": [ "application/json" ], @@ -6403,6 +6403,11 @@ } } }, + "security": [ + { + "ApiKeyAuth": [] + } + ], "summary": "List of users in the org", "tags": [ "Org" @@ -6414,7 +6419,7 @@ "consumes": [ "application/json" ], - "description": "Updates the role of an org user. Note: this endpoint is not APIKEY compatible", + "description": "Updates the role of an org user.", "parameters": [ { "description": "Id of the user", @@ -6441,6 +6446,11 @@ "description": "No Content" } }, + "security": [ + { + "ApiKeyAuth": [] + } + ], "summary": "Update the role of an org user", "tags": [ "Org"