{"_id":"56b217d91bc8490d00701f1b","__v":14,"project":"564e5930c3553e0d003e53d0","parentDoc":null,"version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":26,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"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":2,"slug":"patterns","title":"REST API"},"githubsync":"","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-03T15:08:09.245Z","link_external":false,"link_url":"","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\": \"Secure Connections Required\",\n  \"body\": \"All REST API requests must be made over HTTPS. Connections made using HTTP will be refused.\"\n}\n[/block]\nAll REST API calls require authentication. In order to make successful requests to the REST 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 or user API token. Account 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. For PagerDuty accounts with [Advanced Permissions](https://support.pagerduty.com/docs/advanced-permissions), user API tokens have access to all of the data that the associated user account has access to.\n\nOnly account administrators have the ability to [generate account API tokens](https://support.pagerduty.com/docs/using-the-api#section-generating-a-general-access-rest-api-key).\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": "Secure Connections Required", "body": "All REST API requests must be made over HTTPS. Connections made using HTTP will be refused." } [/block] All REST API calls require authentication. In order to make successful requests to the REST 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 or user API token. Account 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. For PagerDuty accounts with [Advanced Permissions](https://support.pagerduty.com/docs/advanced-permissions), user API tokens have access to all of the data that the associated user account has access to. Only account administrators have the ability to [generate account API tokens](https://support.pagerduty.com/docs/using-the-api#section-generating-a-general-access-rest-api-key). 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]