generate_token

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

📘

Note:

The authenticate method can also be used to generate tokens.

Syntax

{
  <credentials object>
  "user": <mailbox_name>, 
  "reason": <text>,
  "token": <token>,
  "oma": <boolean>,
  "duration": <number of hours>, 
  "type": oma | session | sso
}

Request fields for generate_token

Request fields for generate_token

Field nameObligationDefinition/Value
durationOptionalThe number of hours for which the token is valid. If this value is not specified, the token is valid for 24 hours.
omaOptionalIf set to true, a session or sso type token may also be used with the OMA. If type = oma, this parameter is ignored.

Note: Only company admins can generate tokens with this argument set to true.
reasonRequiredThe reason that the token was generated.
tokenOptionalThe token to add. If this value is not submitted, a random token is generated.
typeOptionalThe type of token to generate.
Allowed values are:

oma — A token that is good for OMA logins only.

Note: This is the same type of token returned by the authenticate method, but this method can generate a token for an arbitrary user.

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).

* 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).

If type is not specified, session is used.
userRequiredThe user's mailbox name.

Response fields for generate_token

The following fields may be returned in response to the generate_token
method:

Field nameObligationDescription/Value
durationReturned if success = trueThe number of hours for which the token is valid.
errorReturned if success = falseA text string that explains the error.
error_numberReturned if success = falseA number that represents the error.
successAlways returnedIndicates whether the request was successful or not. Allowed values are true and false.
tokenReturned if success = trueThe token that was generated.

Examples for generate_token

Example 1

Adds an sso token with default duration.

Request

{
  "credentials": {
  	"user": "[email protected]",
    "password": "pencil75"
  },
  "user": "[email protected]",
  "type": "sso",
  "reason": "Login via portal"
}

Response

{
"success": true,
"duration": 24,
"token": "d39b3ab55786e3a6161f860c3360107c",
}

Example 2

Adds a specific session token with a 3 hour duration.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "pencil75"
  },
  "user": "[email protected]",
  "reason": "User forgot password and needs temporary token to log in", 
  "token": "JaneTophatDishwasher",
  "duration": 3
}

Response

{
  "success": true,
  "duration": 3,
  "token": "JaneTophatDishwasher",
}