Follow-up triggering

Follow-up triggering#

The vast majority of follow-up instruments will require some form of authentication. All such information is passed through the altdata variable of the Allocations API. We briefly describe the authentication form the available telescopes take below:

  • ATLAS Forced Photometry: A user account must be made on https://fallingstar-data.com/forcedphot/, at which point the authentication takes the form {"api_token": "testtoken"}.

  • GENERIC: There are three generic methods for distributing follow-up requests. The first is through API, where the user provides {"notification_type": "API", "endpoint": "API_ENDPOINT", "api_token": "token"} where API_ENDPOINT is the telescope API endpoint. The second is through slack, where the user provides {"notification_type": "slack", "slack_workspace": "XXX", "slack_channel": "YYY", "slack_token": "ZZZ"}, where workspace, channel, and token are the 3 components of a slack webhook URL. The third is by email, where the user provides {"notification_type": "email", "email": "email_1@gmail.com,email_2@gmail.com"}. Both slack and email also allow for {"include_comments": True} to indicate that comment text should also be shared in the message.

  • KAIT: A username and password are passed as {"username": "username", "password": "password"}.

  • LCO: A user account must be made on https://lco.global/, at which point the authentication takes the form {"PROPOSAL_ID": "your_proposal_ID", "API_TOKEN": "testtoken", "API_ARCHIVE_TOKEN": "testarchivetoken"}. The submission token is available directly from https://observe.lco.global while the archive token can be aquired by API: ar = requests.post(’https://archive-api.lco.global/api-token-auth/’, data = {’username’: username, ‘password’: password}) ar_token = ar.json()[’token’]

  • LT: A proposal ID, username, and password are passed as {"username": "username", "password": "password", "LT_proposalID": "your_proposal_ID"}.

  • MMA: There are two generic methods for distributing observation plans. The first is through API, where the user provides {”protocol”: “http/https”, “host”: “host”, “port”: “port”, “access_token”: “token”}, and the second through scp, where the user provides {”host”: “host”, “port”: “port”, “username”: “username”, “password”: “password”, “directory”: “output_directory”}.

  • NICER: A username and password (as entered at https://heasarc.gsfc.nasa.gov/ark/nicertoo/) are passed as {"username": "username", "password": "password"}.

  • SLACK: As discussed further here, slack information is pass as {"slack_workspace": "XXX", "slack_channel": "YYY", "slack_token": "ZZZ"}.

  • SOAR: A user account must be made on https://lco.global/, at which point the authentication takes the form {"PROPOSAL_ID": "your_proposal_ID", "API_TOKEN": "testtoken"}. The submission token is available directly from https://observe.lco.global.

  • SWIFT Triggering: A username and password are passed as {"username": "username", "secret": "password"}.

  • SWIFT XRT Reductions: A user account must be made with the Swift-XRT data products API platform (see https://www.swift.ac.uk/user_objects/register.php to register). The authentication then is the email of the user "XRT_UserID": "swift_email"} where swift_email is the email address used upon sign up.

  • ZTF Triggering: An API token for an admin user for Kowalski can be passed as {"access_token": "your_token"}.

  • ZTF Forced Photometry: A user account must be made with the ZTF forced photometry service (see https://zwicky.tf/vgt). The authentication then takes the form {"ipac_http_user": "http_user", "ipac_http_password": "http_password", "ipac_email": "email", "ipac_userpass": "password"} where http_user and http_password are provided in the documentation and ipac_email and ipac_userpass are provided for the specific account. Note that IPAC’s forced photometry database is updated once per hour, on the hour, and requests will only be available after this update.

  • Gemini (North and South): A user account must be created using Gemini’s Observing Tool (see https://www.gemini.edu/observing). The authentication then takes the form {"email": "email", "password": "password", "progid": "your_proposal_ID"} where email and password are the credentials used to log in to the Observing Tool and progid is the program ID for the observations. Also, the user can submit an optional {"template_ids": "1,2,3"} (comma-separated list of integers) to specify the allowed template IDs to be used for the observations, when submitting follow-up requests to Gemini. If these are specified, the template_id specified when submitting a follow-up request must be one of the allowed template IDs. If not specified, any template ID can be used. Submitted observation requests can be monitored directly from Gemini’s OT.

  • WINTER: The authentication takes the form {"username": "username", "password": "password", "program_name": "program_name", "program_api_key": "program_api_key"}. The credentials are provided by the WINTER team.

In addition to sending requests to their respective API, the SEDM, Swift, and WINTER APIs all take an optional notification_type field. This field can be set to slack to send a notification to a slack channel, or email to send one via email. If using slack, the user must provide slack_workspace, slack_channel, and slack_token fields, that are the 3 components of a slack webhook URL. If using email, the user must provide an email field (which can be a single email, or a comma separated list of emails). Both slack and email also allow for include_comments to be set to True to indicate that comment text should also be shared in the message. These additional fields can simply be added to the altdata dictionary along with the API-specific authentication information.

We plan on adding this notification functionality to all follow-up instruments in the future.

When creating an allocation from the web interface, upon selecting an instrument the relevant altdata fields will be displayed in the form. However when editing an existing allocation, these will not be displayed and the user should refer to this documentation for the correct format. In the future, we plan to also display the altdata fields when editing an allocation.