{"_id":"56b217d91bc8490d00701f1b","__v":14,"project":"564e5930c3553e0d003e53d0","parentDoc":null,"version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":22,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"user":"5668c7855d13810d0060961d","category":{"_id":"56a96d338791090d00113bab","__v":13,"pages":["56a96d492bb3910d000ee931","56c3cec2106c12170020db96","56c51da4ba4a540d0091b9b7","56c51dc3ba4a540d0091b9b9","56c51eb916c7190d00ff7b19","56c51ec2d7b9ed19008d1752","56c51eec668eb01900719bcd","56c51effba4a540d0091b9bb","56c51f1cf7c4da0d00614b02","56c51f2a8dc1c51900abc142","56c51f367de3580d00bdaf2a","56c67b6270e7660d004a8985","56c67b7cfd00bb0d0016daad"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-28T01:21:55.716Z","from_sync":false,"order":1,"slug":"patterns","title":"REST API"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-03T15:08:09.245Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Important: Use SSL\",\n  \"body\": \"All API requests must be made over HTTPS. Connections made using HTTP will be refused.\"\n}\n[/block]\nAll PagerDuty REST APIs require authentication. In order to make successful requests to the API, you must provide a valid form of authorization.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Token Authentication\"\n}\n[/block]\nThe PagerDuty REST API supports authenticating via an account's API token. API tokens have access to all of the data on an account, and can either be granted read-only access or full access to read, write, update, and delete.\n\nOnly account administrators have the ability to [generate API tokens](https://support.pagerduty.com/docs/using-the-api#section-generating-an-api-key). To make it easy to use the v2 API, create a token with v2 selected as the API version.\n\nTokens should be sent in the request as part of an `Authorization` header, using this format:\n\n```\nAuthorization: Token token=w_8PcNuhHa-y3xYdmc1x\n```\n\nBelow is how to set the header in a few popular HTTP libraries. Note that this only sets the header; other code may be needed to create and process the request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var authorizationToken = \\\"w_8PcNuhHa-y3xYdmc1x\\\";\\nfunction pagerdutyRequest(endpoint, method, options) {\\n  $.ajax($.extend({}, {\\n    type: method,\\n    dataType: \\\"json\\\",\\n    url: \\\"https://api.pagerduty.com/\\\" + endpoint,\\n    headers: {\\n      \\\"Authorization\\\": \\\"Token token=\\\" + authorizationToken,\\n      \\\"Accept\\\": \\\"application/vnd.pagerduty+json;version=2\\\"\\n    }\\n  },\\n  options));\\n}\\n\\npagerdutyRequest('users');\",\n      \"language\": \"javascript\",\n      \"name\": \"JavaScript + jQuery\"\n    },\n    {\n      \"code\": \"authorization_token = 'w_8PcNuhHa-y3xYdmc1x'\\npagerduty_session = requests.Session()\\npagerduty_session.headers.update({\\n  'Authorization': 'Token token=' + authorization_token,\\n  'Accept': 'application/vnd.pagerduty+json;version=2'\\n})\\n\\npagerduty_session.get('https://api.pagerduty.com/users')\",\n      \"language\": \"python\",\n      \"name\": \"Python + Requests\"\n    },\n    {\n      \"code\": \"authorization_token = 'w_8PcNuhHa-y3xYdmc1x'\\npagerduty_conn = Faraday.new(url: 'https://api.pagerduty.com') do |conn|\\n  conn.headers['Authorization'] = \\\"Token token=#{authorization_token}\\\"\\n  conn.headers['Accept'] = 'application/vnd.pagerduty+json;version=2'\\n  conn.adapter :net_http\\nend\\n\\npagerduty_conn.get '/users'\",\n      \"language\": \"text\",\n      \"name\": \"Ruby + Faraday\"\n    }\n  ]\n}\n[/block]\nPlease note that this format must be followed precisely or you will receive a `401 Unauthorized` response.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"401 Unauthorized\",\n  \"body\": \"Requests that cannot be authenticated will return a `401 Unauthorized` error response.\\n\\nIf you are receiving a `401`, check:\\n- is your `Authorization` header being sent?\\n- is your `Authorization` header formatted properly?\\n- are you using a valid, active API token?\"\n}\n[/block]","excerpt":"","slug":"authentication","type":"basic","title":"Authentication"}
[block:callout] { "type": "warning", "title": "Important: Use SSL", "body": "All API requests must be made over HTTPS. Connections made using HTTP will be refused." } [/block] All PagerDuty REST APIs require authentication. In order to make successful requests to the API, you must provide a valid form of authorization. [block:api-header] { "type": "basic", "title": "API Token Authentication" } [/block] The PagerDuty REST API supports authenticating via an account's API token. API tokens have access to all of the data on an account, and can either be granted read-only access or full access to read, write, update, and delete. Only account administrators have the ability to [generate API tokens](https://support.pagerduty.com/docs/using-the-api#section-generating-an-api-key). To make it easy to use the v2 API, create a token with v2 selected as the API version. Tokens should be sent in the request as part of an `Authorization` header, using this format: ``` Authorization: Token token=w_8PcNuhHa-y3xYdmc1x ``` Below is how to set the header in a few popular HTTP libraries. Note that this only sets the header; other code may be needed to create and process the request. [block:code] { "codes": [ { "code": "var authorizationToken = \"w_8PcNuhHa-y3xYdmc1x\";\nfunction pagerdutyRequest(endpoint, method, options) {\n $.ajax($.extend({}, {\n type: method,\n dataType: \"json\",\n url: \"https://api.pagerduty.com/\" + endpoint,\n headers: {\n \"Authorization\": \"Token token=\" + authorizationToken,\n \"Accept\": \"application/vnd.pagerduty+json;version=2\"\n }\n },\n options));\n}\n\npagerdutyRequest('users');", "language": "javascript", "name": "JavaScript + jQuery" }, { "code": "authorization_token = 'w_8PcNuhHa-y3xYdmc1x'\npagerduty_session = requests.Session()\npagerduty_session.headers.update({\n 'Authorization': 'Token token=' + authorization_token,\n 'Accept': 'application/vnd.pagerduty+json;version=2'\n})\n\npagerduty_session.get('https://api.pagerduty.com/users')", "language": "python", "name": "Python + Requests" }, { "code": "authorization_token = 'w_8PcNuhHa-y3xYdmc1x'\npagerduty_conn = Faraday.new(url: 'https://api.pagerduty.com') do |conn|\n conn.headers['Authorization'] = \"Token token=#{authorization_token}\"\n conn.headers['Accept'] = 'application/vnd.pagerduty+json;version=2'\n conn.adapter :net_http\nend\n\npagerduty_conn.get '/users'", "language": "text", "name": "Ruby + Faraday" } ] } [/block] Please note that this format must be followed precisely or you will receive a `401 Unauthorized` response. [block:callout] { "type": "danger", "title": "401 Unauthorized", "body": "Requests that cannot be authenticated will return a `401 Unauthorized` error response.\n\nIf you are receiving a `401`, check:\n- is your `Authorization` header being sent?\n- is your `Authorization` header formatted properly?\n- are you using a valid, active API token?" } [/block]