Add basic auth to REST doc and examples (#50758)

Co-authored-by: Sarah Edwards <skedwards88@github.com> Co-authored-by: Peter Bengtsson <peterbe@github.com>
2025-12-19 18:10:59 -05:00 · 2024-06-05 14:45:09 -07:00
parent a2d5f91249
commit 4a5a335d11
14 changed files with 148 additions and 70 deletions
--- a/data/ui.yml
+++ b/data/ui.yml
@@ -182,6 +182,8 @@ rest_reference:
  installation_access_token_name: GitHub App installation access tokens
  fine_grained_access_token_name: Fine-grained personal access tokens
  no_fine_grained_access: This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.
+  basic_auth_heading: Basic authentication for "{{ RESTOperationTitle }}"
+  basic_auth: You must use <a href="/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication">Basic Authentication</a> to use this endpoint. Use the application's <code>client_id</code> as the username and the <code>client_secret</code> as the password.
 webhooks:
  action_type_switch_error: There was an error switching webhook action types.
  action_type: Action type
--- a/src/fixtures/fixtures/data/ui.yml
+++ b/src/fixtures/fixtures/data/ui.yml
@@ -182,6 +182,8 @@ rest_reference:
  installation_access_token_name: GitHub App installation access tokens
  fine_grained_access_token_name: Fine-grained personal access tokens
  no_fine_grained_access: This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.
+  basic_auth_heading: Basic authentication for "{{ RESTOperationTitle }}"
+  basic_auth: You must use <a href="/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication">Basic Authentication</a> to use this endpoint. Use the application's <code>client_id</code> as the username and the <code>client_secret</code> as the password.
 webhooks:
  action_type_switch_error: There was an error switching webhook action types.
  action_type: Action type
--- a/src/github-apps/scripts/sync.js
+++ b/src/github-apps/scripts/sync.js
@@ -185,6 +185,7 @@ export async function getProgAccessData(progAccessSource, isRest = false) {
        : operation.permission_sets || [],
      allowPermissionlessAccess: operation.allows_permissionless_access,
      allowsPublicRead: operation.allows_public_read,
+      basicAuth: operation.basic_auth,
    }
  }

--- a/src/rest/components/RestAuth.tsx
+++ b/src/rest/components/RestAuth.tsx
@@ -16,11 +16,10 @@ const FINE_GRAINED_TOKEN_PATH =
 type Props = {
  progAccess: ProgAccessT
  slug: string
-  heading: string
+  operationTitle: string
 }

-export function RestAuth({ progAccess, slug, heading }: Props) {
-  const router = useRouter()
+export function RestAuth({ progAccess, slug, operationTitle }: Props) {
  const { currentVersion } = useVersion()
  const { t } = useTranslation('rest_reference')

@@ -29,30 +28,48 @@ export function RestAuth({ progAccess, slug, heading }: Props) {
  if (currentVersion === 'enterprise-server@3.9' || currentVersion === 'enterprise-server@3.8')
    return null

-  let basePath = `/${router.locale}`
-  if (currentVersion !== DEFAULT_VERSION) {
-    basePath += `/${currentVersion}`
-  }
-
  // There are some operations that have no progAccess access defined
  // For those operations, we shouldn't display this component
  if (!progAccess) return null
-  const { userToServerRest, serverToServer, fineGrainedPat } = progAccess
+  const { userToServerRest, serverToServer, fineGrainedPat, basicAuth = false } = progAccess
  const noFineGrainedAcccess = !(userToServerRest || serverToServer || fineGrainedPat)

-  // Pluralize the message if needed or customize it
-  // when no permissions are defined
-  const numPermissionSets = progAccess.permissions.length
-  const permissionMsg =
-    numPermissionSets === 0
-      ? t('no_permission_sets')
-      : numPermissionSets > 1
-        ? t('permission_sets') + ':'
-        : t('permission_set') + ':'
-  const publicAccessMsg =
-    numPermissionSets === 0
-      ? t('allows_public_read_access_no_permissions')
-      : t('allows_public_read_access')
+  const heading = basicAuth ? t('basic_auth_heading') : t('fine_grained_access')
+  const headingId = heading.replace('{{ RESTOperationTitle }}', operationTitle)
+  const authSlug = basicAuth
+    ? `${slug}--basic-authentication`
+    : `${slug}--fine-grained-access-tokens`
+
+  return (
+    <>
+      <h3 className="mt-4 mb-3 pt-3 h4" id={authSlug}>
+        <a href={`#${authSlug}`}>{headingId}</a>
+      </h3>
+      {noFineGrainedAcccess ? (
+        <NoFineGrainedAccess basicAuth={basicAuth} />
+      ) : (
+        <FineGrainedAccess progAccess={progAccess} />
+      )}
+    </>
+  )
+}
+
+function NoFineGrainedAccess({ basicAuth }: { basicAuth: boolean }) {
+  const { t } = useTranslation('rest_reference')
+
+  if (basicAuth) return <p dangerouslySetInnerHTML={{ __html: t('basic_auth') }}></p>
+  return <p>{t('no_fine_grained_access')}</p>
+}
+
+type FineGrainedProps = {
+  progAccess: ProgAccessT
+}
+
+function FineGrainedAccess({ progAccess }: FineGrainedProps) {
+  const router = useRouter()
+  const { currentVersion } = useVersion()
+  const { t } = useTranslation('rest_reference')
+
  // progAccess.permissions is an array of objects
  // For example: [ {'"Actions" repository permissions': 'read', '"Administration" organization permissions': 'write'}, {'"Secrets" organization permissions"': 'write'} ]
  // Each object represents a set of permissions containing one
@@ -77,7 +94,26 @@ export function RestAuth({ progAccess, slug, heading }: Props) {
    )
  })

-  const fineGrainedData = (
+  let basePath = `/${router.locale}`
+  if (currentVersion !== DEFAULT_VERSION) {
+    basePath += `/${currentVersion}`
+  }
+
+  // Pluralize the message if needed or customize it
+  // when no permissions are defined
+  const numPermissionSets = progAccess.permissions.length
+  const permissionMsg =
+    numPermissionSets === 0
+      ? t('no_permission_sets')
+      : numPermissionSets > 1
+        ? t('permission_sets') + ':'
+        : t('permission_set') + ':'
+  const publicAccessMsg =
+    numPermissionSets === 0
+      ? t('allows_public_read_access_no_permissions')
+      : t('allows_public_read_access')
+
+  return (
    <>
      <p>{t('works_with_fine_grained_tokens')}:</p>
      <ul>
@@ -106,13 +142,4 @@ export function RestAuth({ progAccess, slug, heading }: Props) {
      {progAccess.allowsPublicRead && <p>{publicAccessMsg}</p>}
    </>
  )
-
-  return (
-    <>
-      <h3 className="mt-4 mb-3 pt-3 h4" id={`${slug}--fine-grained-access-tokens`}>
-        <a href={`#${slug}--fine-grained-access-tokens`}>{heading}</a>
-      </h3>
-      {noFineGrainedAcccess ? <p>{t('no_fine_grained_access')}</p> : fineGrainedData}
-    </>
-  )
 }
--- a/src/rest/components/RestOperation.tsx
+++ b/src/rest/components/RestOperation.tsx
@@ -70,7 +70,7 @@ export function RestOperation({ operation }: Props) {
          <RestAuth
            progAccess={operation.progAccess}
            slug={titleSlug}
-            heading={t('fine_grained_access').replace('{{ RESTOperationTitle }}', operation.title)}
+            operationTitle={operation.title}
          />

          {hasParameters && (
--- a/src/rest/components/get-rest-code-samples.ts
+++ b/src/rest/components/get-rest-code-samples.ts
@@ -93,6 +93,10 @@ export function getShellExample(
    acceptHeader = acceptHeader === `-H "Accept: application/vnd.github+json"` ? '' : acceptHeader
  }

+  if (operation?.progAccess?.basicAuth) {
+    authHeader = '-u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>"'
+  }
+
  const args = [
    operation.verb !== 'get' && `-X ${operation.verb.toUpperCase()}`,
    acceptHeader,
@@ -121,6 +125,9 @@ export function getGHExample(
  currentVersion: string,
  allVersions: Record<string, VersionItem>,
 ) {
+  // Basic authentication is not supported by GH CLI
+  if (operation?.progAccess?.basicAuth) return
+
  const defaultAcceptHeader = getAcceptHeader(codeSample)
  const hostname = operation.serverUrl !== 'https://api.github.com' ? '--hostname HOSTNAME' : ''

@@ -326,9 +333,12 @@ export function getJSExample(
  }

  const comment = `// Octokit.js\n// https://github.com/octokit/core.js#readme\n`
-  const require = `const octokit = new Octokit(${stringify({ auth: 'YOUR-TOKEN' }, null, 2)})\n\n`
+  const authOctokit = `const octokit = new Octokit(${stringify({ auth: 'YOUR-TOKEN' }, null, 2)})\n\n`
+  const oauthOctokit = `import { createOAuthAppAuth } from "@octokit/auth-oauth-app"\n\nconst octokit = new Octokit({\n  authStrategy: createOAuthAppAuth,\n  auth:{\n    clientType: 'oauth-app',\n    clientId: '<YOUR_CLIENT ID>',\n    clientSecret: '<YOUR_CLIENT SECRET>'\n  }\n})\n\n`
+  const isBasicAuth = operation?.progAccess?.basicAuth
+  const authString = isBasicAuth ? oauthOctokit : authOctokit

-  return `${comment}${require}await octokit.request('${operation.verb.toUpperCase()} ${
+  return `${comment}${authString}await octokit.request('${operation.verb.toUpperCase()} ${
    operation.requestPath
  }${queryParameters}', ${stringify(parameters, null, 2)})`
 }
--- a/src/rest/components/types.ts
+++ b/src/rest/components/types.ts
@@ -21,6 +21,7 @@ export interface ProgAccessT {
  permissions: Array<Object>
  allowPermissionlessAccess?: boolean
  allowsPublicRead?: boolean
+  basicAuth?: boolean
 }

 export interface Parameter {
--- a/src/rest/data/fpt-2022-11-28/schema.json
+++ b/src/rest/data/fpt-2022-11-28/schema.json
@@ -84928,7 +84928,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -96146,7 +96147,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -96217,7 +96219,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -97227,7 +97230,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -98233,7 +98237,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
--- a/src/rest/data/ghec-2022-11-28/schema.json
+++ b/src/rest/data/ghec-2022-11-28/schema.json
@@ -94538,7 +94538,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -105756,7 +105757,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -105827,7 +105829,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -106837,7 +106840,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -107843,7 +107847,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
--- a/src/rest/data/ghes-3.10-2022-11-28/schema.json
+++ b/src/rest/data/ghes-3.10-2022-11-28/schema.json
@@ -93569,7 +93569,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -101792,7 +101793,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -101863,7 +101865,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102848,7 +102851,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -103829,7 +103833,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
--- a/src/rest/data/ghes-3.11-2022-11-28/schema.json
+++ b/src/rest/data/ghes-3.11-2022-11-28/schema.json
@@ -93593,7 +93593,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -101816,7 +101817,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -101887,7 +101889,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102872,7 +102875,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -103853,7 +103857,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
--- a/src/rest/data/ghes-3.12-2022-11-28/schema.json
+++ b/src/rest/data/ghes-3.12-2022-11-28/schema.json
@@ -93769,7 +93769,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102077,7 +102078,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102148,7 +102150,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -103150,7 +103153,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -104148,7 +104152,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
--- a/src/rest/data/ghes-3.13-2022-11-28/schema.json
+++ b/src/rest/data/ghes-3.13-2022-11-28/schema.json
@@ -93861,7 +93861,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102209,7 +102210,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102280,7 +102282,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -103290,7 +103293,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -104296,7 +104300,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
--- a/src/rest/data/ghes-3.9-2022-11-28/schema.json
+++ b/src/rest/data/ghes-3.9-2022-11-28/schema.json
@@ -92555,7 +92555,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -100774,7 +100775,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -100845,7 +100847,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -101830,7 +101833,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {
@@ -102811,7 +102815,8 @@
          "userToServerRest": false,
          "serverToServer": false,
          "fineGrainedPat": false,
-          "permissions": []
+          "permissions": [],
+          "basicAuth": true
        },
        "codeExamples": [
          {