[WIP] Generate authorization role guide

docs/guides/_toc.json

@@ -976,6 +976,10 @@
               "title": "Activity tracking events for the IBM Quantum System service",
               "url": "/docs/guides/observability-quantum-system"
             },
+            {
+              "title": "Authorization roles",
+              "url": "/docs/guides/authorization-roles"
+            },
             {
               "title": "Repository security policies",
               "url": "/docs/guides/security-policies"

docs/guides/authorization-roles.mdx

@@ -0,0 +1,55 @@
+---
+title: Authorization roles
+description: Learn about the authorization roles and permissions available for the IBM Quantum REST APIs.
+---
+
+# Authorization roles
+
+{/* TODO: Prose to be added by the team. */}
+
+## Qiskit Runtime
+
+| Permission | Required by |
+| -- | -- |
+| `quantum-computing.account-analytics-filters.read` | Get analytics filters (`GET /v1/analytics/filters`) |
+| `quantum-computing.account-analytics-usage.read` | Get usage analytics (`GET /v1/analytics/usage`) |
+| `quantum-computing.account-analytics-usage.read` | Get usage analytics grouped (`GET /v1/analytics/usage_grouped`) |
+| `quantum-computing.account-analytics-usage.read` | Get usage analytics grouped by date (`GET /v1/analytics/usage_grouped_by_date`) |
+| `quantum-computing.account-configuration.read` | Get account configuration (`GET /v1/accounts/{id}`) |
+| `quantum-computing.device.read` | Get backend configuration (`GET /v1/backends/{id}/configuration`) |
+| `quantum-computing.device.read` | Get backend default settings (`GET /v1/backends/{id}/defaults`) |
+| `quantum-computing.device.read` | Get backend properties (`GET /v1/backends/{id}/properties`) |
+| `quantum-computing.device.read` | Get backend status (`GET /v1/backends/{id}/status`) |
+| `quantum-computing.device.read` | List your backends (`GET /v1/backends`) |
+| `quantum-computing.instance-usage.read` | Get instance usage (`GET /v1/instances/usage`) |
+| `quantum-computing.instance.configuration.read` | Get instance configuration (`GET /v1/instances/configuration`) |
+| `quantum-computing.instance.read` | Get current instance details (`GET /v1/instance`) |
+| `quantum-computing.job.cancel` | Cancel a job (`POST /v1/jobs/{id}/cancel`) |
+| `quantum-computing.job.create` | Run a job (`POST /v1/jobs`) |
+| `quantum-computing.job.delete` | Delete a job (`DELETE /v1/jobs/{id}`) |
+| `quantum-computing.job.read` | Get job metrics (`GET /v1/jobs/{id}/metrics`) |
+| `quantum-computing.job.read` | List job details (`GET /v1/jobs/{id}`) |
+| `quantum-computing.job.read` | List job logs (`GET /v1/jobs/{id}/logs`) |
+| `quantum-computing.job.read` | List job results (`GET /v1/jobs/{id}/results`) |
+| `quantum-computing.job.read` | List jobs (`GET /v1/jobs`) |
+| `quantum-computing.job.read` | List tags (`GET /v1/tags`) |
+| `quantum-computing.session.create` | Create a session (`POST /v1/sessions`) |
+| `quantum-computing.session.read` | Get a session (`GET /v1/sessions/{id}`) |
+| `quantum-computing.session.update` | Close job session (`DELETE /v1/sessions/{id}/close`) |
+| `quantum-computing.session.update` | Update a session (`PATCH /v1/sessions/{id}`) |
+| `quantum-computing.workload.list` | List user instance workloads (`GET /v1/workloads`) |
+
+## The IBM Quantum System service
+
+| Permission | Required by |
+| -- | -- |
+| `quantum-computing.direct-access-backend-configuration.read` | Get backend configuration (`GET /v1/backends/{backend-name}/configuration`) |
+| `quantum-computing.direct-access-backend-properties.read` | Get backend properties (`GET /v1/backends/{backend-name}/properties`) |
+| `quantum-computing.direct-access-backend.list` | Get list of backends (`GET /v1/backends`) |
+| `quantum-computing.direct-access-backend.read` | Get backend details (`GET /v1/backends/{backend-name}`) |
+| `quantum-computing.direct-access-job.cancel` | Cancel a job (`POST /v1/jobs/{job-id}/cancel`) |
+| `quantum-computing.direct-access-job.create` | Run a job (`POST /v1/jobs`) |
+| `quantum-computing.direct-access-job.delete` | Delete a job (`DELETE /v1/jobs/{job-id}`) |
+| `quantum-computing.direct-access-job.list` | Get jobs (`GET /v1/jobs`) |
+| `quantum-computing.direct-access-job.read` | Get Job by ID (`GET /v1/jobs/{job-id}`) |
+| `quantum-computing.direct-access-lane-configuration.list` | Get backend lanes configuration (`GET /v1/backends/{backend-name}/lanes`) |

qiskit_bot.yaml

@@ -296,6 +296,9 @@ notifications:
   "docs/guides/observability-quantum-system":
     - "`@abbycross`"
     - "`@beckykd`"
+  "docs/guides/authorization-roles":
+    - "`@abbycross`"
+    - "`@beckykd`"
   "docs/guides/responsibilities":
     - "@abbycross"
     - "@beckykd"

scripts/js/commands/generateRestApiGuides.ts

@@ -27,6 +27,7 @@ const PACKAGE_TO_URL: Record<OpenapiPkgTitle, string> = {
 };
 
 async function main() {
+  // Activity tracking events, one guide per API.
   await writeObservabilityFile(
     RUNTIME_API_TITLE,
     "docs/guides/observability-runtime-rest.mdx",
@@ -35,12 +36,18 @@ async function main() {
     QUANTUM_SYSTEM_API_TITLE,
     "docs/guides/observability-quantum-system.mdx",
   );
+  // Authorization roles, a single guide with a section per API.
+  await writeAuthorizationFile("docs/guides/authorization-roles.mdx");
 }
 
 function maybeAddPkgTitleRegisteredIcon(pkgTitle: string) {
   return pkgTitle.replace("IBM", "IBM&reg;");
 }
 
+function toSectionTitle(pkgTitle: string): string {
+  return pkgTitle.charAt(0).toUpperCase() + pkgTitle.slice(1);
+}
+
 async function writeObservabilityFile(
   pkgTitle: OpenapiPkgTitle,
   destPath: string,
@@ -54,6 +61,24 @@ async function writeObservabilityFile(
   console.log(`✅ Wrote ${destPath}`);
 }
 
+async function writeAuthorizationFile(destPath: string) {
+  const pkgTitles: OpenapiPkgTitle[] = [
+    RUNTIME_API_TITLE,
+    QUANTUM_SYSTEM_API_TITLE,
+  ];
+  const sections = pkgTitles.map(async (pkgTitle) => {
+    const response = await fetch(PACKAGE_TO_URL[pkgTitle]);
+    const jsonstr = await response.text();
+    const endpoints = extractEndpoints(jsonstr, "x-ibm-permissions", "actions");
+    const table = generateTable(endpoints, "Permission", "Required by");
+    return `## ${toSectionTitle(pkgTitle)}\n\n${table}`;
+  });
+  const body = (await Promise.all(sections)).join("\n");
+  const mdx = `${getAuthorizationProse()}\n${body}`;
+  await writeFile(destPath, mdx, "utf8");
+  console.log(`✅ Wrote ${destPath}`);
+}
+
 const RUNTIME_REGION_SECTION = `
 ## Locations where activity tracking events are generated
 
@@ -89,4 +114,16 @@ For information on launching the IBM Cloud Logs UI, see the [Launching the UI](h
 `;
 }
 
+function getAuthorizationProse(): string {
+  return `---
+title: Authorization roles
+description: Learn about the authorization roles and permissions available for the IBM Quantum REST APIs.
+---
+
+# Authorization roles
+
+{/* TODO: Prose to be added by the team. */}
+`;
+}
+
 main().then(() => process.exit());