{"_id":"56b4d1cf5f1cf00d00cc46d7","githubsync":"","__v":20,"category":{"_id":"56b25826147e900d00d6497a","project":"569f9cf6650e1d1900f96b5b","version":"569f9cf6650e1d1900f96b5e","pages":["56b2583a9621f20d00efb31c","56b25a3965ddf50d0076baa2","56b2738894ab060d0006743c","56b4d1cf5f1cf00d00cc46d7","56b4f4e2b1a8690d00a59369","56b4f6925f1cf00d00cc4704","56b4fa3d5997532100bc6bcc","56b50ba8eed075230097d71e","56b5123585a6922300d1c506","56b51e475997532100bc6c08","56b5220b7719bb1900143055","56b524cc3d5f130d00dad1b8","56b5265b168b5c1700c15996","56b774438fb4420d006a618b","56b78012eb783a0d007894f3","56b78292a6c10c0d00a2d65d","56b7863aeb783a0d007894f8","56b78f68a6c10c0d00a2d66b","56b794566c2a240d0094ae8a","56b7a85dd22adc0d0053f4c2","56b7ac118fb4420d006a61b7"],"__v":21,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-03T19:42:30.051Z","from_sync":false,"order":7,"slug":"user-methods","title":"User methods"},"project":"569f9cf6650e1d1900f96b5b","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"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-05T16:46:07.069Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The [authenticate](https://api-opensrs-email.readme.io/v1.0/docs/authenticate?bypass=8272e34bb5) method can also be used to generate tokens.\",\n  \"title\": \"Note:\"\n}\n[/block]\n## Syntax \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  <credentials object>\\n  \\\"user\\\": <mailbox_name>, \\n  \\\"reason\\\": <text>,\\n  \\\"token\\\": <token>,\\n  \\\"oma\\\": <boolean>,\\n  \\\"duration\\\": <number of hours>, \\n  \\\"type\\\": oma | session | sso\\n}\",\n      \"language\": \"text\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request fields for generate_token\"\n}\n[/block]\nRequest fields for **generate_token** \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"duration\",\n    \"0-1\": \"Optional\",\n    \"0-2\": \"The number of hours for which the token is valid. If this value is not specified, the token is valid for 24 hours.\",\n    \"1-0\": \"oma\",\n    \"1-1\": \"Optional\",\n    \"1-2\": \"If set to **true**, a **session** or **sso** type token may also be used with the OMA. If **type = oma**, this parameter is ignored.\\n\\n**Note**: Only company admins can generate tokens with this argument set to **true**.\",\n    \"2-0\": \"reason\",\n    \"2-1\": \"Required\",\n    \"2-2\": \"The reason that the token was generated.\",\n    \"3-0\": \"token\",\n    \"3-1\": \"Optional\",\n    \"3-2\": \"The token to add. If this value is not submitted, a random token is generated.\",\n    \"4-0\": \"type\",\n    \"4-1\": \"Optional\",\n    \"4-2\": \"The type of token to generate. \\nAllowed values are:\\n\\n  * **oma** — A token that is good for OMA logins only. \\n\\n  **Note**: This is the same type of token returned by the **authenticate** method, but this method can generate a token for an arbitrary user.\\n\\n  * **session** — Valid until the duration of the token expires. Can be used for mail services and as credentials for the OMA (if oma is true in the request).\\n\\n  * **sso** — A single use token that becomes invalid after it is used once. Can be used to log in to mail services (Webmail, IMAP, SMPT, etc) and the oma (if oma is true in the request).\\n \\nIf **type** is not specified, **session** is used.\",\n    \"5-0\": \"user\",\n    \"5-1\": \"Required\",\n    \"5-2\": \"The user's mailbox name.\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response fields for generate_token\"\n}\n[/block]\nThe following fields may be returned in response to the **generate_token**\nmethod:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Description/Value\",\n    \"0-0\": \"duration\",\n    \"0-1\": \"Returned if **success = true**\",\n    \"0-2\": \"The number of hours for which the token is valid.\",\n    \"1-0\": \"error\",\n    \"1-1\": \"Returned if **success = false**\",\n    \"1-2\": \"A text string that explains the error.\",\n    \"2-0\": \"error_number\",\n    \"2-1\": \"Returned if **success = false**\",\n    \"2-2\": \"A number that represents the error.\",\n    \"3-0\": \"success\",\n    \"3-1\": \"Always returned\",\n    \"3-2\": \"Indicates whether the request was successful or not. Allowed values are **true** and **false**.\",\n    \"4-0\": \"token\",\n    \"4-1\": \"Returned if **success = true**\",\n    \"4-2\": \"The token that was generated.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples for generate_token\"\n}\n[/block]\n**Example 1**\n\nAdds an sso token with default duration.\n\n**Request** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n  \\t\\\"user\\\": \\\"domain_admin:::at:::example.com\\\",\\n    \\\"password\\\": \\\"pencil75\\\"\\n  },\\n  \\\"user\\\": \\\"joe_user@example.com\\\",\\n  \\\"type\\\": \\\"sso\\\",\\n  \\\"reason\\\": \\\"Login via portal\\\"\\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\\\"duration\\\": 24,\\n\\\"token\\\": \\\"d39b3ab55786e3a6161f860c3360107c\\\",\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n## Example 2\n\nAdds a specific session token with a 3 hour duration.\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  \\\"user\\\": \\\"jane_user@example.com\\\",\\n  \\\"reason\\\": \\\"User forgot password and needs temporary token to log in\\\", \\n  \\\"token\\\": \\\"JaneTophatDishwasher\\\",\\n  \\\"duration\\\": 3\\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  \\\"duration\\\": 3,\\n  \\\"token\\\": \\\"JaneTophatDishwasher\\\",\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]","excerpt":"The **generate_token** method generates a temporary login token for a user. Tokens can be used in place of a password.","slug":"generate_token","type":"basic","title":"generate_token"}

generate_token

The **generate_token** method generates a temporary login token for a user. Tokens can be used in place of a password.

[block:callout] { "type": "info", "body": "The [authenticate](https://api-opensrs-email.readme.io/v1.0/docs/authenticate?bypass=8272e34bb5) method can also be used to generate tokens.", "title": "Note:" } [/block] ## Syntax [block:code] { "codes": [ { "code": "{\n <credentials object>\n \"user\": <mailbox_name>, \n \"reason\": <text>,\n \"token\": <token>,\n \"oma\": <boolean>,\n \"duration\": <number of hours>, \n \"type\": oma | session | sso\n}", "language": "text", "name": " " } ] } [/block] [block:api-header] { "type": "basic", "title": "Request fields for generate_token" } [/block] Request fields for **generate_token** [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "duration", "0-1": "Optional", "0-2": "The number of hours for which the token is valid. If this value is not specified, the token is valid for 24 hours.", "1-0": "oma", "1-1": "Optional", "1-2": "If set to **true**, a **session** or **sso** type token may also be used with the OMA. If **type = oma**, this parameter is ignored.\n\n**Note**: Only company admins can generate tokens with this argument set to **true**.", "2-0": "reason", "2-1": "Required", "2-2": "The reason that the token was generated.", "3-0": "token", "3-1": "Optional", "3-2": "The token to add. If this value is not submitted, a random token is generated.", "4-0": "type", "4-1": "Optional", "4-2": "The type of token to generate. \nAllowed values are:\n\n * **oma** — A token that is good for OMA logins only. \n\n **Note**: This is the same type of token returned by the **authenticate** method, but this method can generate a token for an arbitrary user.\n\n * **session** — Valid until the duration of the token expires. Can be used for mail services and as credentials for the OMA (if oma is true in the request).\n\n * **sso** — A single use token that becomes invalid after it is used once. Can be used to log in to mail services (Webmail, IMAP, SMPT, etc) and the oma (if oma is true in the request).\n \nIf **type** is not specified, **session** is used.", "5-0": "user", "5-1": "Required", "5-2": "The user's mailbox name." }, "cols": 3, "rows": 6 } [/block] [block:api-header] { "type": "basic", "title": "Response fields for generate_token" } [/block] The following fields may be returned in response to the **generate_token** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Description/Value", "0-0": "duration", "0-1": "Returned if **success = true**", "0-2": "The number of hours for which the token is valid.", "1-0": "error", "1-1": "Returned if **success = false**", "1-2": "A text string that explains the error.", "2-0": "error_number", "2-1": "Returned if **success = false**", "2-2": "A number that represents the error.", "3-0": "success", "3-1": "Always returned", "3-2": "Indicates whether the request was successful or not. Allowed values are **true** and **false**.", "4-0": "token", "4-1": "Returned if **success = true**", "4-2": "The token that was generated." }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "Examples for generate_token" } [/block] **Example 1** Adds an sso token with default duration. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \t\"user\": \"domain_admin@example.com\",\n \"password\": \"pencil75\"\n },\n \"user\": \"joe_user@example.com\",\n \"type\": \"sso\",\n \"reason\": \"Login via portal\"\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n\"success\": true,\n\"duration\": 24,\n\"token\": \"d39b3ab55786e3a6161f860c3360107c\",\n}", "language": "perl", "name": " " } ] } [/block] ## Example 2 Adds a specific session token with a 3 hour duration. **Request** [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n \"user\": \"domain_admin@example.com\",\n \"password\": \"pencil75\"\n },\n \"user\": \"jane_user@example.com\",\n \"reason\": \"User forgot password and needs temporary token to log in\", \n \"token\": \"JaneTophatDishwasher\",\n \"duration\": 3\n}", "language": "perl", "name": " " } ] } [/block] **Response** [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"duration\": 3,\n \"token\": \"JaneTophatDishwasher\",\n}", "language": "perl", "name": " " } ] } [/block]