{"_id":"5d2d0bcef45fbf006c6cb3c5","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,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-07-15T23:27:10.996Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"# Overview #\n\n[Create an app](https://v2.developer.pagerduty.com/docs/how-to-build-an-app) to get access to OAuth 2 credentials.\n\nPagerDuty supports OAuth 2.0’s [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow for [third-party applications](https://v2.developer.pagerduty.com/docs/how-to-build-an-app) to obtain access tokens from PagerDuty and utilizes the following endpoints:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Authorization Endpoint\",\n    \"1-0\": \"Token Endpoint\",\n    \"1-1\": \"https://app.pagerduty.com/oauth/token\",\n    \"0-1\": \"https://app.pagerduty.com/oauth/authorize\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\nThe following parameters will also be used in your requests or returned in the response:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`client_id`\",\n    \"0-1\": \"An identifier issued when the app is created. \\n<span style=\\\"color:red\\\">Required for authorization request.</span>\\n<span style=\\\"color:red\\\">Required for token request.</span>\",\n    \"1-0\": \"`client_secret`\",\n    \"1-1\": \"A secret issued when the app is created. \\n<span style=\\\"color:red\\\">Required for token request.</span>\",\n    \"2-0\": \"`code`\",\n    \"2-1\": \"The authorization code issued upon a successful authorization request. \\n<span style=\\\"color:red\\\">Required for token request.</span>\",\n    \"4-0\": \"`redirect_uri`\",\n    \"4-1\": \"Registered with the app when OAuth 2.0 is added. \\n<span style=\\\"color:red\\\">Required for authorization request.</span>\\n<span style=\\\"color:red\\\">Required for token request.</span>\",\n    \"5-0\": \"`response_type`\",\n    \"5-1\": \"Specifies the response type based on OAuth 2.0 flow. Value must be set to `code`.\\n<span style=\\\"color:red\\\">Required for authorization request.</span>\",\n    \"6-0\": \"`subdomain`\",\n    \"6-1\": \"The subdomain of the user authorizing the app.\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"3-0\": \"`grant_type`\",\n    \"3-1\": \"The OAuth 2.0 grant type. Value must be set to `authorization_code`.\\n<span style=\\\"color:red\\\">Required for token request.</span>\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n# Obtaining an Access Token #\n\nSend a GET request to authorization endpoint with query parameters set for `client_id` and `redirect_uri`, as defined in the app, and `response_type=code`\n\n```\nGET https://app.pagerduty.com/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code\n```\n\n### Authorized Requests ###\n\nIf the user authorizes the app, PagerDuty will redirect to the specified URI with the `code` (authorization code) in the URL:\n```\n{REDIRECT_URI}?code={AUTHORIZATION_CODE}&subdomain={ACCOUNT_SUBDOMAIN}\n```\n\n### Denied Requests ###\n\nIf the user denies authorization, PagerDuty will redirect to the specified URI with `error` and `error_description` parameters: \n\n```\n{REDIRECT_URI}?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&subdomain={ACCOUNT_SUBDOMAIN}\n```\n\n### Exchanging Authorization Code ###\n\nTo exchange the authorization code for an access token, send a POST request to the token endpoint. The authorization code has a time to live of 10 minutes, and your POST request must be received within that time. Additionally, specify the following query parameters when making the request: `client_id`, `client_secret`, `redirect_uri`, the `code` (authorization code) received from PagerDuty, and `grant_type=authorization_code`.\n\n```\nPOST https://app.pagerduty.com/oauth/token?grant_type=authorization_code&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&redirect_uri={REDIRECT_URI}&code={CODE}\n```\n\nThe access token will be included in a JSON response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"access_token\\\":\\\"9937611c354d287d3ff509afdde5b1d6d500c73a67387d666ca1e8e3d502d516\\\",\\n  \\\"token_type\\\":\\\"bearer\\\",\\n  \\\"scope\\\":\\\"user\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Authorized Response\"\n    }\n  ]\n}\n[/block]\n# Using an Access Token #\n\nOnce obtained, access tokens can be used to make [REST API](https://api-reference.pagerduty.com/#!/API_Reference/get_api_reference) requests on behalf of the user.\n\nWhen making an API request, include the version of the API in the `Accept` header. Access tokens must also be sent in the request as part of the `Authorization` header along with the `Bearer` token type, using this format:\n\n```\nAuthorization: Bearer 9937611c354d287d3ff509afdde5b1d6d500c73a67387d666ca1e8e3d502d516\nAccept: application/vnd.pagerduty+json;version=2\n```\n\nThe token can be used continuously to make requests until the user or app owner revokes it.","excerpt":"","slug":"oauth-2-functionality","type":"basic","title":"OAuth 2 Functionality"}

OAuth 2 Functionality


# Overview # [Create an app](https://v2.developer.pagerduty.com/docs/how-to-build-an-app) to get access to OAuth 2 credentials. PagerDuty supports OAuth 2.0’s [Authorization Code Grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow for [third-party applications](https://v2.developer.pagerduty.com/docs/how-to-build-an-app) to obtain access tokens from PagerDuty and utilizes the following endpoints: [block:parameters] { "data": { "0-0": "Authorization Endpoint", "1-0": "Token Endpoint", "1-1": "https://app.pagerduty.com/oauth/token", "0-1": "https://app.pagerduty.com/oauth/authorize" }, "cols": 2, "rows": 2 } [/block] The following parameters will also be used in your requests or returned in the response: [block:parameters] { "data": { "0-0": "`client_id`", "0-1": "An identifier issued when the app is created. \n<span style=\"color:red\">Required for authorization request.</span>\n<span style=\"color:red\">Required for token request.</span>", "1-0": "`client_secret`", "1-1": "A secret issued when the app is created. \n<span style=\"color:red\">Required for token request.</span>", "2-0": "`code`", "2-1": "The authorization code issued upon a successful authorization request. \n<span style=\"color:red\">Required for token request.</span>", "4-0": "`redirect_uri`", "4-1": "Registered with the app when OAuth 2.0 is added. \n<span style=\"color:red\">Required for authorization request.</span>\n<span style=\"color:red\">Required for token request.</span>", "5-0": "`response_type`", "5-1": "Specifies the response type based on OAuth 2.0 flow. Value must be set to `code`.\n<span style=\"color:red\">Required for authorization request.</span>", "6-0": "`subdomain`", "6-1": "The subdomain of the user authorizing the app.", "h-0": "Parameter", "h-1": "Description", "3-0": "`grant_type`", "3-1": "The OAuth 2.0 grant type. Value must be set to `authorization_code`.\n<span style=\"color:red\">Required for token request.</span>" }, "cols": 2, "rows": 7 } [/block] # Obtaining an Access Token # Send a GET request to authorization endpoint with query parameters set for `client_id` and `redirect_uri`, as defined in the app, and `response_type=code` ``` GET https://app.pagerduty.com/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code ``` ### Authorized Requests ### If the user authorizes the app, PagerDuty will redirect to the specified URI with the `code` (authorization code) in the URL: ``` {REDIRECT_URI}?code={AUTHORIZATION_CODE}&subdomain={ACCOUNT_SUBDOMAIN} ``` ### Denied Requests ### If the user denies authorization, PagerDuty will redirect to the specified URI with `error` and `error_description` parameters: ``` {REDIRECT_URI}?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&subdomain={ACCOUNT_SUBDOMAIN} ``` ### Exchanging Authorization Code ### To exchange the authorization code for an access token, send a POST request to the token endpoint. The authorization code has a time to live of 10 minutes, and your POST request must be received within that time. Additionally, specify the following query parameters when making the request: `client_id`, `client_secret`, `redirect_uri`, the `code` (authorization code) received from PagerDuty, and `grant_type=authorization_code`. ``` POST https://app.pagerduty.com/oauth/token?grant_type=authorization_code&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&redirect_uri={REDIRECT_URI}&code={CODE} ``` The access token will be included in a JSON response: [block:code] { "codes": [ { "code": "{\n \"access_token\":\"9937611c354d287d3ff509afdde5b1d6d500c73a67387d666ca1e8e3d502d516\",\n \"token_type\":\"bearer\",\n \"scope\":\"user\"\n}", "language": "json", "name": "Authorized Response" } ] } [/block] # Using an Access Token # Once obtained, access tokens can be used to make [REST API](https://api-reference.pagerduty.com/#!/API_Reference/get_api_reference) requests on behalf of the user. When making an API request, include the version of the API in the `Accept` header. Access tokens must also be sent in the request as part of the `Authorization` header along with the `Bearer` token type, using this format: ``` Authorization: Bearer 9937611c354d287d3ff509afdde5b1d6d500c73a67387d666ca1e8e3d502d516 Accept: application/vnd.pagerduty+json;version=2 ``` The token can be used continuously to make requests until the user or app owner revokes it.