update titles for REST API apps docs (#49556)
This commit is contained in:
Sarah Edwards
@@ -82,7 +82,7 @@ When you use a user access token, you should track which organizations the token
|
||||
|
||||
{% data variables.product.company_short %} strongly encourages you to use user access tokens that expire. If you previously opted out of using user access tokens that expire but want to re-enable this feature, see "[AUTOTITLE](/apps/maintaining-github-apps/activating-optional-features-for-github-apps)."
|
||||
|
||||
Installation access tokens expire after one hour, expiring user access tokens expire after eight hours, and refresh tokens expire after six months. However, you can also revoke tokens as soon as you no longer need them. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token.
|
||||
Installation access tokens expire after one hour, expiring user access tokens expire after eight hours, and refresh tokens expire after six months. However, you can also revoke tokens as soon as you no longer need them. For more information, see "[`DELETE /installation/token`](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[`DELETE /applications/{client_id}/token`](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token.
|
||||
|
||||
## Cache tokens
|
||||
|
||||
@@ -94,7 +94,7 @@ You should have a plan in place so that you can handle any security breaches in
|
||||
|
||||
In the event that your app's private key or secret is compromised, you will need to generate a new key or secret, update your app to use the new key or secret, and delete your old key or secret.
|
||||
|
||||
In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see "[AUTOTITLE](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[AUTOTITLE](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token.
|
||||
In the event that installation access tokens, user access tokens, or refresh tokens are compromised, you should immediately revoke these tokens. For more information, see "[`DELETE /installation/token`](/rest/apps/installations#revoke-an-installation-access-token)" to revoke an installation access token and "[`DELETE /applications/{client_id}/token`](/rest/apps/oauth-applications#delete-an-app-token)" to revoke a user access token.
|
||||
|
||||
## Conduct regular vulnerability scans
|
||||
|
||||
|
||||
@@ -75,7 +75,7 @@ After the customer completes the authorization, your app receives an OAuth acces
|
||||
|
||||
## Step 4. Provisioning customer accounts
|
||||
|
||||
Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[AUTOTITLE](/rest/apps#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning.
|
||||
Your app must provision a customer account for all new purchases. Using the access token you received for the customer in [Step 3. Authorization](#step-3-authorization), call the "[`GET /user/marketplace_purchases`](/rest/apps/marketplace#list-subscriptions-for-the-authenticated-user)" endpoint. The response will include the customer's `account` information and show whether they are on a free trial (`on_free_trial`). Use this information to complete setup and provisioning.
|
||||
|
||||
{% data reusables.marketplace.marketplace-double-purchases %}
|
||||
|
||||
|
||||
@@ -60,7 +60,7 @@ https://www.github.com/marketplace/<LISTING_NAME>/upgrade/<LISTING_PLAN_NUMBER>/
|
||||
|
||||
For example, if you notice that a customer is on a 5 person plan and needs to move to a 10 person plan, you could display a button in your app's UI that says "Here's how to upgrade" or show a banner with a link to the upgrade URL. The upgrade URL takes the customer to your listing plan's upgrade confirmation page.
|
||||
|
||||
Use the `LISTING_PLAN_NUMBER` for the plan the customer would like to purchase. When you create new pricing plans they receive a `LISTING_PLAN_NUMBER`, which is unique to each plan across your listing, and a `LISTING_PLAN_ID`, which is unique to each plan in the {% data variables.product.prodname_marketplace %}. You can find these numbers when you [List plans](/rest/apps#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the "[AUTOTITLE](/rest/apps#list-accounts-for-a-plan)" endpoint to get the `CUSTOMER_ACCOUNT_ID`.
|
||||
Use the `LISTING_PLAN_NUMBER` for the plan the customer would like to purchase. When you create new pricing plans they receive a `LISTING_PLAN_NUMBER`, which is unique to each plan across your listing, and a `LISTING_PLAN_ID`, which is unique to each plan in the {% data variables.product.prodname_marketplace %}. You can find these numbers when you [List plans](/rest/apps#list-plans), which identifies your listing's pricing plans. Use the `LISTING_PLAN_ID` and the "[`GET /marketplace_listing/plans/{plan_id}/accounts`](/rest/apps/marketplace#list-accounts-for-a-plan)" endpoint to get the `CUSTOMER_ACCOUNT_ID`.
|
||||
|
||||
{% note %}
|
||||
|
||||
|
||||
@@ -71,7 +71,7 @@ See "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/reviewing-
|
||||
|
||||
## Resetting API tokens
|
||||
|
||||
If you have any applications registered with {% data variables.product.product_name %}, you'll want to reset their OAuth tokens. For more information, see the "[AUTOTITLE](/rest/apps#reset-an-authorization)" endpoint.
|
||||
If you have any applications registered with {% data variables.product.product_name %}, you'll want to reset their OAuth tokens. For more information, see the `PATCH /applications/{client_id}/token` endpoint in "[AUTOTITLE](/rest/apps/oauth-applications#reset-a-token)."
|
||||
|
||||
## Preventing unauthorized access
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: GitHub Apps
|
||||
title: 'REST API endpoints for {% data variables.product.prodname_github_apps %}'
|
||||
shortTitle: '{% data variables.product.prodname_github_apps %}'
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: >-
|
||||
Use the REST API to interact with {% data
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
title: Apps
|
||||
title: REST API endpoints for apps
|
||||
shortTitle: Apps
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: 'Use the REST API to retrieve information about {% data variables.product.prodname_github_apps %} and {% data variables.product.prodname_github_app %} installations.'
|
||||
redirect_from:
|
||||
- /v3/apps
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: GitHub App installations
|
||||
title: 'REST API endpoints for {% data variables.product.prodname_github_app %} installations'
|
||||
allowTitleToDifferFromFilename: true
|
||||
shortTitle: Installations
|
||||
intro: >-
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: GitHub Marketplace
|
||||
title: 'REST API endpoints for {% data variables.product.prodname_marketplace %}'
|
||||
allowTitleToDifferFromFilename: true
|
||||
shortTitle: Marketplace
|
||||
intro: >-
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
title: OAuth Authorizations
|
||||
title: REST API endpoints for OAuth authorizations
|
||||
shortTitle: OAuth authorizations
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: >-
|
||||
Use the REST API to interact with {% data
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: GitHub App webhooks
|
||||
title: 'REST API endpoints for {% data variables.product.prodname_github_app %} webhooks'
|
||||
allowTitleToDifferFromFilename: true
|
||||
shortTitle: Webhooks
|
||||
intro: >-
|
||||
|
||||
@@ -55,7 +55,7 @@ const octokit = new Octokit({ {% ifversion ghes %}
|
||||
|
||||
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will indicate what type of {% data variables.product.prodname_github_app %} token is required. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)."
|
||||
|
||||
Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)" in the REST reference documentation.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
|
||||
Instead of importing `Octokit` from `octokit`, import `App`. In the following example, replace `APP_ID` with a reference to your app's ID. Replace `PRIVATE_KEY` with a reference to your app's private key. Replace `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)."{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
|
||||
|
||||
```javascript copy
|
||||
import { App } from "octokit";
|
||||
|
||||
@@ -52,7 +52,7 @@ octokit = Octokit::Client.new(access_token: 'YOUR-TOKEN')
|
||||
|
||||
If you want to use the API on behalf of an organization or another user, {% data variables.product.company_short %} recommends that you use a {% data variables.product.prodname_github_app %}. If an endpoint is available to {% data variables.product.prodname_github_apps %}, the REST reference documentation for that endpoint will indicate what type of {% data variables.product.prodname_github_app %} token is required. For more information, see "[AUTOTITLE](/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)."
|
||||
|
||||
Instead of requiring `octokit`, create an instance of `Octokit::Client` by passing your {% data variables.product.prodname_github_app %}'s information as options. In the following example, replace `APP_ID` with your app's ID, `PRIVATE_KEY` with your app's private key, and `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)" in the REST reference documentation.{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
|
||||
Instead of requiring `octokit`, create an instance of `Octokit::Client` by passing your {% data variables.product.prodname_github_app %}'s information as options. In the following example, replace `APP_ID` with your app's ID, `PRIVATE_KEY` with your app's private key, and `INSTALLATION_ID` with the ID of the installation of your app that you want to authenticate on behalf of. You can find your app's ID and generate a private key on the settings page for your app. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." You can get an installation ID with the `GET /users/{username}/installation`, `GET /repos/{owner}/{repo}/installation`, or `GET /orgs/{org}/installation` endpoints. For more information, see "[AUTOTITLE](/rest/apps/apps)."{% ifversion ghes %} Replace `HOSTNAME` with the name of {% data variables.location.product_location %}.{% endif %}
|
||||
|
||||
```ruby copy
|
||||
require 'octokit'
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
title: OAuth authorizations
|
||||
title: REST API endpoints for OAuth app authorizations
|
||||
shortTitle: OAuth app authorizations
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: Use the REST API to manage the access {% data variables.product.prodname_oauth_apps %} have to your account.
|
||||
versions:
|
||||
ghes: '*'
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
---
|
||||
title: OAuth authorizations
|
||||
title: REST API endpoints for OAuth app authorizations
|
||||
shortTitle: OAuth app authorizations
|
||||
allowTitleToDifferFromFilename: true
|
||||
intro: >-
|
||||
Use the REST API to manage the access {% data
|
||||
variables.product.prodname_oauth_apps %} have to your account.
|
||||
|
||||
@@ -63,7 +63,7 @@ jobs:
|
||||
|
||||
If you are authenticating with a {% data variables.product.prodname_github_app %}, you can create an installation access token within your workflow:
|
||||
|
||||
1. Store your {% data variables.product.prodname_github_app %}'s ID as a configuration variable. In the following example, replace `APP_ID` with the name of the configuration variable. You can find your app ID on the settings page for your app or through the API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)" in the REST API documentation. For more information about configuration variables, see "[AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)."
|
||||
1. Store your {% data variables.product.prodname_github_app %}'s ID as a configuration variable. In the following example, replace `APP_ID` with the name of the configuration variable. You can find your app ID on the settings page for your app or through the API. For more information, see "[AUTOTITLE](/rest/apps/apps#get-an-app)." For more information about configuration variables, see "[AUTOTITLE](/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)."
|
||||
1. Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`.) In the following example, replace `APP_PEM` with the name of the secret. For more information, see "[AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)." For more information about secrets, see "[AUTOTITLE](/actions/security-guides/encrypted-secrets)."
|
||||
1. Add a step to generate a token, and use that token instead of `GITHUB_TOKEN`. Note that this token will expire after 60 minutes. {% ifversion fpt or ghec %}For example:{% else %}In the following example, replace `HOSTNAME` with the name of {% data variables.location.product_location %}. Replace `REPO-OWNER` with the name of the account that owns the repository. Replace `REPO-NAME` with the name of the repository.{% endif %}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user