API Command: generate_session_key
The generate_session_key command creates a new session key to be used in starting a support session. Note that if your B Series Appliance has multiple public sites, the session key created may be associated with any of these sites, depending on the method used to download the customer client.
For example, Site A has a hostname of support.example.com, and Site B has a hostname of remote.example.com. When a generate_session_key request is made to support.example.com with a url_hostname of support.example.com, both a session key code and a unique session key URL will be generated.
If the customer goes to the generated URL to download the customer client, then the session will be associated with Site B, because the session key URL points to the hostname designated by the url_hostname parameter.
However, the customer could also download the customer client by submitting the session key code on either site. Therefore, if the customer goes to Site A to submit the code, then the session will be associated with Site A, while if they go to Site B, the session will be associated with Site B.
The command API is an authenticated API. For instructions on using authenticated APIs using OAuth, see Authenticate to the Remote Support API. The API account must have full access to the command API.
Required Parameters for generate_session_key
| type=[string] | The type of session for which you would like to generate a session key. Currently, the only supported value is support. |
| queue_id=[string] |
The queue in which the session should be placed. Can be one of general, rep:[id], or team:[id], where [id] is the numeric ID for the representative, or team queue in which you wish to place this session. Can also be rep_username:[username]. This call will work only if a single user with the given username exists; otherwise, an error message will be returned. Can also be issue:[issue_code_name]. To get a representative's ID, see API Command: get_logged_in_reps. To get a team's ID, see API Command: get_support_teams. |
Optional Parameters for generate_session_key
|
session.custom.external_key=[string] |
An arbitrary string that can link this session to an identifier on an external system, such as a help desk ticket ID. This has a maximum length of 1024 characters. |
| session.custom.[custom field]=[string] |
The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB. |
| session.priority=[integer] | The priority of the session, from 1 to 3. 1 = high, 2 = medium, and 3 = low. |
| session.skills=[string] | A comma-separated list of the code names of skills to assign to a session. |
| ttl=[integer] | Time in seconds for which this key should be valid. If omitted, the maximum session key timeout set in the administrative interface will be used. |
| url_hostname=[string] | Hostname to use in the URL generated for the session key. Defaults to the primary hostname for your BeyondTrust Appliance B Series. |
If a parameter is set via generate_session_key and is then overwritten via another API (e.g., start_session) then the second attribute will take precedence.
XML Response for generate_session_key Query
| <type> | The type of session for which this key was generated. Currently, the only supported value is support. |
| <ttl> | Time in seconds for which this key is valid. |
| <expires> | The timestamp at which this session key expires. |
| <queue> |
The queue in which this session will be placed. This value will be rep or team. Also contains an available attribute. For a session key targeting a representative, the value is 1 if that representative is logged in. For a session key targeting a team, |
| <queue_id> | The numeric ID of the queue. |
| <external_key> | A string that links this session to an identifier on an external system, such as a help desk ticket ID. |
| <short_key> | The seven-character string that the customer can enter on your public site to start a session. |
| <key_url> | The session key url to which the customer can go to start a session. |
| <mail_subject> | The subject line of the session key email invitation. This is static text defined by BeyondTrust and is not configurable. |
| <mail_body> | The body of the session key email invitation. This is static text defined by BeyondTrust and is not configurable. |
Query Examples: generate_session_key
| Specific representative by ID |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=rep:1 |
| Specific team |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1 |
| Specific representative by username |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=rep_username:admin |
| Specific issue |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=issue:other |
| Specific team, 1 hour time to live |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&ttl=3600 |
| Specific team, external key and custom field |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&session.custom.external_key=ABC1234&session.custom.custom_field1=Custom%20Value |
| Specific team, specific hostname |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&url_hostname=support.example.com |
| Specific team, skills and priority set |
https://support.example.com/api/command?action=generate_session_key&type=support&queue_id=team:1&session.priority=1&session.skills=codename1,codename2 |
