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 name

Obligation

Definition/Value

duration

Optional

The number of hours for which the token is valid. If this value is not specified, the token is valid for 24 hours.

oma

Optional

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

reason

Required

The reason that the token was generated.

token

Optional

The token to add. If this value is not submitted, a random token is generated.

type

Optional

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

user

Required

The user's mailbox name.

Response fields for generate_token

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

Field name

Obligation

Description/Value

duration

Returned if success = true

The number of hours for which the token is valid.

error

Returned if success = false

A text string that explains the error.

error_number

Returned if success = false

A number that represents the error.

success

Always returned

Indicates whether the request was successful or not. Allowed values are true and false.

token

Returned if success = true

The 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",
}