{"_id":"56ad309ecdbb3d170064eaef","project":"569f9cf6650e1d1900f96b5b","category":{"_id":"56ad2f8b1c09150d00a183a8","project":"569f9cf6650e1d1900f96b5b","version":"569f9cf6650e1d1900f96b5e","pages":["56ad30493fc1020d009776df","56ad309ecdbb3d170064eaef","56ad4c2c0ab3c00d00ce3354"],"__v":3,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-30T21:47:55.396Z","from_sync":false,"order":3,"slug":"authentication-methods","title":"Authentication Methods"},"githubsync":"","user":"5582e90181672a3900bb4fc7","version":{"_id":"569f9cf6650e1d1900f96b5e","project":"569f9cf6650e1d1900f96b5b","__v":12,"createdAt":"2016-01-20T14:43:02.785Z","releaseDate":"2016-01-20T14:43:02.785Z","categories":["569f9cf7650e1d1900f96b5f","56abdd81d4432d1900eed235","56abe0558beeff0d003b8118","56ad2f8b1c09150d00a183a8","56ad4e1cd21f1b0d00fd2f97","56b00ad88f7a4f0d0029dc92","56b2432e9621f20d00efb2bd","56b25826147e900d00d6497a","56b7af2a4b372d2100722c48","56b8c4d938b1070d0028920f","56b8cdab14feef0d0082415d","58599813cf9e112d0032cdab"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":18,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-01-30T21:52:30.087Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This method allows you to verify a user's credentials. You do not need to issue this request before submitting other methods however, since all methods contain a credentials object.\",\n  \"title\": \"Note:\"\n}\n[/block]\n**Syntax** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t<credentials object>: {\\n  \\t\\\"fetch_extra_info\\\": true | false \\n  \\t\\\"generate_session_token\\\": true | false \\n  \\t\\\"token\\\": string \\n  \\t\\\"session_token_duration\\\": \\\"seconds\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request fields for authenticate\"\n}\n[/block]\nThe following fields can be used in the **authenticate** method:\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"fetch_extra_info\",\n    \"0-1\": \"Optional\",\n    \"0-2\": \"Returns additional information about the user. If set to **true**, the response will contain the **extra_info** field.\",\n    \"1-0\": \"generate_session_token\",\n    \"1-1\": \"Optional\",\n    \"1-2\": \"If set to **true**, returns a session token and the duration of the token.\",\n    \"2-0\": \"session_token_duration\",\n    \"2-1\": \"Optional\",\n    \"2-2\": \"The duration of the session token, in seconds. Value can be a number between **1** and **86400** (24 hours). If not specified, the default is **10800** (3 hours).\\n\\n**Note**: This field is ignored unless **generate_session_token** = **true**.\",\n    \"3-0\": \"token\",\n    \"3-1\": \"Optional\",\n    \"3-2\": \"Specify the token that you want to use. If **generate_session_token** is true, this string will be used as the token.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response fields for authenticate\"\n}\n[/block]\nThe following fields may be returned in response to the authenticate\nmethod:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Description/Value\",\n    \"0-0\": \"error\",\n    \"0-1\": \"Returned if **success = false**\",\n    \"0-2\": \"A text string that explains the error.\",\n    \"1-0\": \"error_number\",\n    \"1-1\": \"Returned if **success = false**\",\n    \"1-2\": \"A number that represents the error.\",\n    \"2-0\": \"extra_info\",\n    \"2-1\": \"Returned if **success = true** and request contains **fetch_extra_info**.\",\n    \"2-2\": \"A list of the user's attributes that may be useful for an interactive client to populate a UI.\",\n    \"3-0\": \"session_token\",\n    \"3-1\": \"Returned if **success = true** and request contains **generate_session_token = true**\",\n    \"3-2\": \"A generated string that can be used in place of the user's password for a limited time. The time begins when the request is submitted and lasts for the number of seconds specified in **session_token_duration**.\",\n    \"4-0\": \"session_token_duration\",\n    \"4-1\": \"Returned if **success = true** and request contains **generate_session_token = true**\",\n    \"4-2\": \"The number of seconds for which the session token is active. If **session_token_duration** is not specified in the request, this value defaults to 10800 (3 hours); otherwise, it uses the value submitted in the request.\",\n    \"5-0\": \"success\",\n    \"5-1\": \"Always returned\",\n    \"5-2\": \"Indicates whether the request was successful or not. Allowed values are **TRUE** and **FALSE**.\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples for authenticate\"\n}\n[/block]\n## Example 1 \n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"credentials\\\": {\\n        \\\"user\\\": \\\"domain_admin:::at:::example.com\\\",\\n        \\\"password\\\": \\\"sw0rdf1sh\\\"\\n    }\\n    \\\"fetch_extra_into\\\": true,\\n    \\\"generate_session_token\\\": true\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"extra_info\\\": {\\n        \\\"roles\\\": {\\n            \\\"domain\\\": [\\n                \\\"example.com\\\"\\n            ]\\n        },\\n        \\\"macsettings\\\": \\\"entries_per_page=30;theme=default;search_pages=50;loglevel=90;lang=en; \\\"\\n    },\\n    \\\"session_token\\\": \\\"69da1a00117f157537ce785230414ddd\\\",\\n    \\\"session_token_duration\\\": 10800,\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 2 \n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n    \\\"user\\\": \\\"domain_admin@example.com\\\", \\n    \\\"password\\\": \\\"pencil75\\\"\\n  },\\n  \\\"fetch_extra_info\\\": true,\\n  \\\"generate_session_token\\\": true,\\n  \\\"token\\\": \\\"gabbagabba\\\"\\n} \\n\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{ \\n\\\"success\\\": true,\\n  \\\"extra_info\\\": {\\n    \\\"roles\\\": {\\n      \\\"domain\\\": [\\n        \\\"example.com\\\"\\n      ]\\n    }, \\n    \\\"macsettings\\\": null\\n  },\\n  \\\"session_token\\\": \\\"gabbagabba\\\",\\n  \\\"session_token_duration\\\": 10800,\\n  \\\"audit\\\": \\\"flesh36_4f183f46b\\\"\\n} \",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]","excerpt":"The **authenticate** method verifies a set of user credentials.","slug":"authenticate","type":"basic","title":"authenticate"}

authenticate

The **authenticate** method verifies a set of user credentials.

[block:callout] { "type": "info", "body": "This method allows you to verify a user's credentials. You do not need to issue this request before submitting other methods however, since all methods contain a credentials object.", "title": "Note:" } [/block] **Syntax** [block:code] { "codes": [ { "code": "{\n\t<credentials object>: {\n \t\"fetch_extra_info\": true | false \n \t\"generate_session_token\": true | false \n \t\"token\": string \n \t\"session_token_duration\": \"seconds\"\n}", "language": "perl", "name": " " } ] } [/block] [block:api-header] { "type": "basic", "title": "Request fields for authenticate" } [/block] The following fields can be used in the **authenticate** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "fetch_extra_info", "0-1": "Optional", "0-2": "Returns additional information about the user. If set to **true**, the response will contain the **extra_info** field.", "1-0": "generate_session_token", "1-1": "Optional", "1-2": "If set to **true**, returns a session token and the duration of the token.", "2-0": "session_token_duration", "2-1": "Optional", "2-2": "The duration of the session token, in seconds. Value can be a number between **1** and **86400** (24 hours). If not specified, the default is **10800** (3 hours).\n\n**Note**: This field is ignored unless **generate_session_token** = **true**.", "3-0": "token", "3-1": "Optional", "3-2": "Specify the token that you want to use. If **generate_session_token** is true, this string will be used as the token." }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "type": "basic", "title": "Response fields for authenticate" } [/block] The following fields may be returned in response to the authenticate method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Description/Value", "0-0": "error", "0-1": "Returned if **success = false**", "0-2": "A text string that explains the error.", "1-0": "error_number", "1-1": "Returned if **success = false**", "1-2": "A number that represents the error.", "2-0": "extra_info", "2-1": "Returned if **success = true** and request contains **fetch_extra_info**.", "2-2": "A list of the user's attributes that may be useful for an interactive client to populate a UI.", "3-0": "session_token", "3-1": "Returned if **success = true** and request contains **generate_session_token = true**", "3-2": "A generated string that can be used in place of the user's password for a limited time. The time begins when the request is submitted and lasts for the number of seconds specified in **session_token_duration**.", "4-0": "session_token_duration", "4-1": "Returned if **success = true** and request contains **generate_session_token = true**", "4-2": "The number of seconds for which the session token is active. If **session_token_duration** is not specified in the request, this value defaults to 10800 (3 hours); otherwise, it uses the value submitted in the request.", "5-0": "success", "5-1": "Always returned", "5-2": "Indicates whether the request was successful or not. Allowed values are **TRUE** and **FALSE**." }, "cols": 3, "rows": 6 } [/block] [block:api-header] { "type": "basic", "title": "Examples for authenticate" } [/block] ## Example 1 **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"sw0rdf1sh\"\n }\n \"fetch_extra_into\": true,\n \"generate_session_token\": true\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"extra_info\": {\n \"roles\": {\n \"domain\": [\n \"example.com\"\n ]\n },\n \"macsettings\": \"entries_per_page=30;theme=default;search_pages=50;loglevel=90;lang=en; \"\n },\n \"session_token\": \"69da1a00117f157537ce785230414ddd\",\n \"session_token_duration\": 10800,\n}", "language": "perl", "name": " " } ] } [/block] ## Example 2 **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\", \n \"password\": \"pencil75\"\n },\n \"fetch_extra_info\": true,\n \"generate_session_token\": true,\n \"token\": \"gabbagabba\"\n} \n", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{ \n\"success\": true,\n \"extra_info\": {\n \"roles\": {\n \"domain\": [\n \"example.com\"\n ]\n }, \n \"macsettings\": null\n },\n \"session_token\": \"gabbagabba\",\n \"session_token_duration\": 10800,\n \"audit\": \"flesh36_4f183f46b\"\n} ", "language": "perl", "name": " " } ] } [/block]