{"_id":"5d26438f38d460003ea9e8bf","project":"564e5930c3553e0d003e53d0","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":27,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999","5d1d0c9f19c3a0003aeb525a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"category":{"_id":"5d1d0c9f19c3a0003aeb525a","project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2019-07-03T20:14:23.802Z","from_sync":false,"order":2,"slug":"app-integration-development","title":"App / Integration Development"},"user":"5bbfe5dfe752030003c5cb52","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-07-10T19:59:11.520Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Apps are associated with a PagerDuty subdomain and a user, and once created, apps cannot be moved between subdomains or users. Continued access to this subdomain and user is needed to make any configuration changes to the app.\",\n  \"title\": \"Requirements\"\n}\n[/block]\n# Accessing Developer Mode\n\n1. Log in to your PagerDuty account.\n2. From the top menu, select the ![icon](https://files.readme.io/67e682a-app_icon.png) icon to the left of the profile picture.\n3. Select **Developer Mode** from the menu to navigate to the **My Apps** page.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ac254cb-app-accessing-dev-mode.png\",\n        \"app-accessing-dev-mode.png\",\n        421,\n        48,\n        \"#1c2434\"\n      ]\n    }\n  ]\n}\n[/block]\n# Creating an App\n\n1. On the **My Apps** page in **Developer Mode**, select **Create New App**.\n2. On the **Build an App** page, enter the **App Name** and **Brief Description**. Then select **Category** from the drop-down menu. \n3. Select **Where can this app be installed?** from the drop-down to indicate if the app is intended to be used privately on the app’s account (Only on this account) or to be shared publicly (Any account by any user or organization). PagerDuty gathers this information to understand how app builders are using their apps and this option does not restrict app installation.\n4. Click **Save**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ee4e14e-app-configure.png\",\n        \"app-configure.png\",\n        715,\n        680,\n        \"#2a4a3b\"\n      ],\n      \"sizing\": \"full\"\n    }\n  ]\n}\n[/block]\n1. On the **Configure App** page, review the information provided on the previous page, and, if necessary, make any changes at this time.\n2. *Optional*: provide an **App Website URL** where users can learn more about the app.\n3. *Optional*: provide the **Icon URL**, a link to a hosted image file that will display with the app. Icons should be sized 50px by 50px. Once the image link is input, the image will display to the side and in the **Preview** box.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/86c514e-app-preview-box.png\",\n        \"app-preview-box.png\",\n        659,\n        162,\n        \"#dcdcdc\"\n      ]\n    }\n  ]\n}\n[/block]\n1. Review the PagerDuty **Service Terms of Use**.\n2. Click **Save** when finished configuring the app. A green banner will appear at the top confirming the app was created.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/aef3435-app-save-successful.png\",\n        \"app-save-successful.png\",\n        652,\n        135,\n        \"#d2e3da\"\n      ]\n    }\n  ]\n}\n[/block]\n1. The app is now available to view from **My Apps** page, linked in the top navigation.\n\n## Installing OAuth 2.0\n\nInstalling OAuth 2.0 is necessary for app authentication with PagerDuty. You can also review our [sample OAuth 2.0 app](https://github.com/PagerDuty/pagerduty-oauth-sample-node) for an example of how to build an app that uses OAuth 2.0 authentication.\n\n1. On the **My Apps** page in **Developer Mode**, select the app.\n2. On the **Configure App** page under **Functionality**, select the OAuth 2 **Add** button.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/8b26772-app-add-oauth.png\",\n        \"app-add-oauth.png\",\n        1286,\n        282,\n        \"#1c1c1c\"\n      ]\n    }\n  ]\n}\n[/block]\n1. On the **Add User Authorization** page, enter a **Redirect URL**. PagerDuty will only redirect users to a URL saved to your OAuth configuration. Click **Save**.\n2. *Optional*: add additional redirect URLs to be used by the app.\n3. Under **Tokens**, the app’s **Client ID** and **Client Secret** are displayed. The Client ID is public and will be used to identify the app when it authenticates with PagerDuty. The Client Secret should be stored securely and must not be shared publicly. If the Client Secret has been compromised, select **Regenerate** to create a new Client Secret. \n4. Under **Scopes** and **Set Permission Scopes**, select an option from the drop-down. By default, the app does not have any permissions set. There are two scope options: **Read** or **Read/Write**. These scopes are tied to the user’s permissions. Authenticated users will only be able to read and write to objects that they have access to.\n5. It is recommended to **Add a message to users** to let them know what data the app will access and how the app will utilize that data. This message will be displayed on the **Authorization Required** screen when the user authenticates the app.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b95368b-app-authroization-message.png\",\n        \"app-authroization-message.png\",\n        1436,\n        614,\n        \"#d94339\"\n      ]\n    }\n  ]\n}\n[/block]\n1. Under **Danger Zone**, there are options to delete OAuth from the app and revoke all user tokens. Deleting OAuth will immediately prevent the app from authenticating with PagerDuty and effectively disable it for all users. Revoking all user tokens will require all users to reauthorize the app on their account. As these actions directly affect the end-users of the app, they should be used with caution.\n2. After configuring OAuth 2.0, select **Save**.\n\nCongratulations! OAuth 2.0 is successfully configured for the app.","excerpt":"","slug":"how-to-build-an-app","type":"basic","title":"How to Build an App"}

How to Build an App


[block:callout] { "type": "warning", "body": "Apps are associated with a PagerDuty subdomain and a user, and once created, apps cannot be moved between subdomains or users. Continued access to this subdomain and user is needed to make any configuration changes to the app.", "title": "Requirements" } [/block] # Accessing Developer Mode 1. Log in to your PagerDuty account. 2. From the top menu, select the ![icon](https://files.readme.io/67e682a-app_icon.png) icon to the left of the profile picture. 3. Select **Developer Mode** from the menu to navigate to the **My Apps** page. [block:image] { "images": [ { "image": [ "https://files.readme.io/ac254cb-app-accessing-dev-mode.png", "app-accessing-dev-mode.png", 421, 48, "#1c2434" ] } ] } [/block] # Creating an App 1. On the **My Apps** page in **Developer Mode**, select **Create New App**. 2. On the **Build an App** page, enter the **App Name** and **Brief Description**. Then select **Category** from the drop-down menu. 3. Select **Where can this app be installed?** from the drop-down to indicate if the app is intended to be used privately on the app’s account (Only on this account) or to be shared publicly (Any account by any user or organization). PagerDuty gathers this information to understand how app builders are using their apps and this option does not restrict app installation. 4. Click **Save**. [block:image] { "images": [ { "image": [ "https://files.readme.io/ee4e14e-app-configure.png", "app-configure.png", 715, 680, "#2a4a3b" ], "sizing": "full" } ] } [/block] 1. On the **Configure App** page, review the information provided on the previous page, and, if necessary, make any changes at this time. 2. *Optional*: provide an **App Website URL** where users can learn more about the app. 3. *Optional*: provide the **Icon URL**, a link to a hosted image file that will display with the app. Icons should be sized 50px by 50px. Once the image link is input, the image will display to the side and in the **Preview** box. [block:image] { "images": [ { "image": [ "https://files.readme.io/86c514e-app-preview-box.png", "app-preview-box.png", 659, 162, "#dcdcdc" ] } ] } [/block] 1. Review the PagerDuty **Service Terms of Use**. 2. Click **Save** when finished configuring the app. A green banner will appear at the top confirming the app was created. [block:image] { "images": [ { "image": [ "https://files.readme.io/aef3435-app-save-successful.png", "app-save-successful.png", 652, 135, "#d2e3da" ] } ] } [/block] 1. The app is now available to view from **My Apps** page, linked in the top navigation. ## Installing OAuth 2.0 Installing OAuth 2.0 is necessary for app authentication with PagerDuty. You can also review our [sample OAuth 2.0 app](https://github.com/PagerDuty/pagerduty-oauth-sample-node) for an example of how to build an app that uses OAuth 2.0 authentication. 1. On the **My Apps** page in **Developer Mode**, select the app. 2. On the **Configure App** page under **Functionality**, select the OAuth 2 **Add** button. [block:image] { "images": [ { "image": [ "https://files.readme.io/8b26772-app-add-oauth.png", "app-add-oauth.png", 1286, 282, "#1c1c1c" ] } ] } [/block] 1. On the **Add User Authorization** page, enter a **Redirect URL**. PagerDuty will only redirect users to a URL saved to your OAuth configuration. Click **Save**. 2. *Optional*: add additional redirect URLs to be used by the app. 3. Under **Tokens**, the app’s **Client ID** and **Client Secret** are displayed. The Client ID is public and will be used to identify the app when it authenticates with PagerDuty. The Client Secret should be stored securely and must not be shared publicly. If the Client Secret has been compromised, select **Regenerate** to create a new Client Secret. 4. Under **Scopes** and **Set Permission Scopes**, select an option from the drop-down. By default, the app does not have any permissions set. There are two scope options: **Read** or **Read/Write**. These scopes are tied to the user’s permissions. Authenticated users will only be able to read and write to objects that they have access to. 5. It is recommended to **Add a message to users** to let them know what data the app will access and how the app will utilize that data. This message will be displayed on the **Authorization Required** screen when the user authenticates the app. [block:image] { "images": [ { "image": [ "https://files.readme.io/b95368b-app-authroization-message.png", "app-authroization-message.png", 1436, 614, "#d94339" ] } ] } [/block] 1. Under **Danger Zone**, there are options to delete OAuth from the app and revoke all user tokens. Deleting OAuth will immediately prevent the app from authenticating with PagerDuty and effectively disable it for all users. Revoking all user tokens will require all users to reauthorize the app on their account. As these actions directly affect the end-users of the app, they should be used with caution. 2. After configuring OAuth 2.0, select **Save**. Congratulations! OAuth 2.0 is successfully configured for the app.