{"_id":"5de6f72645bfc2005da74967","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":"59e10aa4bf9ac7001a235dd6","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-12-04T00:00:38.826Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"## What is OAuth 2 functionality?\nOAuth 2 allows your app to connect to our [REST API](https://api-reference.pagerduty.com/) as a PagerDuty user (not full account access) to administer PagerDuty or get data (create an on-call schedule, get a list of team members, etc).\n\n## Why should I use OAuth 2?\nWith OAuth 2, you can present a user with a prompt to log in with their PagerDuty account and authorize your app to access their PagerDuty data. \n\nThis is a simple and seamless process for the user and more secure because as an app developer you can:\n* Limit your access to read-only\n* Scope your access to the permissions of a specific user\n* Allow PagerDuty users to monitor and revoke access to your app at any time\n* Eliminate copying and pasting API tokens which could lead to the token falling into the wrong hands\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/59d7ea6-oauth_authorize.png\",\n        \"oauth_authorize.png\",\n        2124,\n        1146,\n        \"#f3f3f3\"\n      ]\n    }\n  ]\n}\n[/block]\n## Add OAuth 2 functionality to your app\n1. [Create an app in PagerDuty](doc:how-to-build-an-app)\n\n2. In the **Functionality** section, click **Add** on the OAuth 2 card.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/d7cb8fd-oauth2_functionality.png\",\n        \"oauth2_functionality.png\",\n        1434,\n        630,\n        \"#d7d7d8\"\n      ]\n    }\n  ]\n}\n[/block]\n3. On the next page, enter a **Redirect URL**. PagerDuty will only redirect users to a URL saved to your OAuth configuration. Click **Save**. You can edit or add redirect URLs later.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/3bdd26e-redirect_url.png\",\n        \"redirect_url.png\",\n        1436,\n        576,\n        \"#e1e3e6\"\n      ]\n    }\n  ]\n}\n[/block]\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 - PKCE does not require the use of client_secret. If the Client Secret has been compromised, select **Regenerate** to create a new Client Secret. \n4. Under **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. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/dc08dae-oauth_scopes.png\",\n        \"oauth_scopes.png\",\n        1442,\n        902,\n        \"#e0e1e2\"\n      ]\n    }\n  ]\n}\n[/block]\nCongratulations! OAuth 2 is successfully configured for the app. Now you can move on to in\n\n## Implementing OAuth / Choosing An OAuth Flow\n\nThere two options for implementing PagerDuty OAuth in your app. [PKCE (Proof Key for Code Exchange)](doc:oauth-2-functionality-pkce) is recommended and should work for all apps. The [Authorization Code Grant](doc:oauth-2-functionality-client-secret) Flow is also supported.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"[PCKE - Proof Key for Code Exchange](doc:oauth-2-functionality-pkce) **(Recommended)**\",\n    \"h-1\": \"Server-side App*\",\n    \"h-0\": \"Choose A Flow For Your App:\",\n    \"0-1\": \"Yes\",\n    \"h-2\": \"Client-side App**\",\n    \"0-2\": \"Yes\",\n    \"1-2\": \"No\",\n    \"1-0\": \"[Authorization Code Grant](doc:oauth-2-functionality-client-secret)\",\n    \"1-1\": \"Yes\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n** *Client-side App** - an app which runs in the browser or a native mobile app\n** *Server-side App** - an app running on a server which can securely store secrets\n\n## Removing OAuth 2 Functionality\nSee [Removing Functionality From Your App](doc:app-functionality#section-removing-functionality-from-your-app)","excerpt":"","slug":"oauth-2-functionality","type":"basic","title":"OAuth 2 Functionality"}

OAuth 2 Functionality


## What is OAuth 2 functionality? OAuth 2 allows your app to connect to our [REST API](https://api-reference.pagerduty.com/) as a PagerDuty user (not full account access) to administer PagerDuty or get data (create an on-call schedule, get a list of team members, etc). ## Why should I use OAuth 2? With OAuth 2, you can present a user with a prompt to log in with their PagerDuty account and authorize your app to access their PagerDuty data. This is a simple and seamless process for the user and more secure because as an app developer you can: * Limit your access to read-only * Scope your access to the permissions of a specific user * Allow PagerDuty users to monitor and revoke access to your app at any time * Eliminate copying and pasting API tokens which could lead to the token falling into the wrong hands [block:image] { "images": [ { "image": [ "https://files.readme.io/59d7ea6-oauth_authorize.png", "oauth_authorize.png", 2124, 1146, "#f3f3f3" ] } ] } [/block] ## Add OAuth 2 functionality to your app 1. [Create an app in PagerDuty](doc:how-to-build-an-app) 2. In the **Functionality** section, click **Add** on the OAuth 2 card. [block:image] { "images": [ { "image": [ "https://files.readme.io/d7cb8fd-oauth2_functionality.png", "oauth2_functionality.png", 1434, 630, "#d7d7d8" ] } ] } [/block] 3. On the next page, enter a **Redirect URL**. PagerDuty will only redirect users to a URL saved to your OAuth configuration. Click **Save**. You can edit or add redirect URLs later. [block:image] { "images": [ { "image": [ "https://files.readme.io/3bdd26e-redirect_url.png", "redirect_url.png", 1436, 576, "#e1e3e6" ] } ] } [/block] 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 - PKCE does not require the use of client_secret. If the Client Secret has been compromised, select **Regenerate** to create a new Client Secret. 4. Under **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. [block:image] { "images": [ { "image": [ "https://files.readme.io/dc08dae-oauth_scopes.png", "oauth_scopes.png", 1442, 902, "#e0e1e2" ] } ] } [/block] Congratulations! OAuth 2 is successfully configured for the app. Now you can move on to in ## Implementing OAuth / Choosing An OAuth Flow There two options for implementing PagerDuty OAuth in your app. [PKCE (Proof Key for Code Exchange)](doc:oauth-2-functionality-pkce) is recommended and should work for all apps. The [Authorization Code Grant](doc:oauth-2-functionality-client-secret) Flow is also supported. [block:parameters] { "data": { "0-0": "[PCKE - Proof Key for Code Exchange](doc:oauth-2-functionality-pkce) **(Recommended)**", "h-1": "Server-side App*", "h-0": "Choose A Flow For Your App:", "0-1": "Yes", "h-2": "Client-side App**", "0-2": "Yes", "1-2": "No", "1-0": "[Authorization Code Grant](doc:oauth-2-functionality-client-secret)", "1-1": "Yes" }, "cols": 3, "rows": 2 } [/block] ** *Client-side App** - an app which runs in the browser or a native mobile app ** *Server-side App** - an app running on a server which can securely store secrets ## Removing OAuth 2 Functionality See [Removing Functionality From Your App](doc:app-functionality#section-removing-functionality-from-your-app)