Commit 7c3e3dae authored by Tanner Prestegard's avatar Tanner Prestegard

Add documentation on reloading certificates

parent f5e79527
......@@ -25,6 +25,33 @@ If you are working behind a proxy, use the ``proxy_host`` and ``proxy_port`` arg
More information about the client class and the options which can be provided to the constructor is covered in detail on the :ref:`api:API` page.
Credentials
-----------
Credentials are not required, but users who possess them will likely want to authenticate in order to gain full access to the GraceDB server.
X.509 certificates
~~~~~~~~~~~~~~~~~~
LIGO/Virgo users can provide an X.509 certificate to the client for authenticating to the GraceDB server.
This can be a proxy certificate which is generated by ``ligo-proxy-init``, another certificate which has been registered with the LIGO auth system, or a robot certificate.
There are multiple methods for making these credentials available to the client class, detailed in the documentation for :py:class:`ligo.gracedb.rest.GraceDb`.
These certificates may expire after some period of time and need to be renewed.
If you have long-running jobs where the lifetime of a client may exceed that of your certificate,
use the ``reload_certificate`` argument (and optionally, the ``reload_buffer`` argument) when instantiating a client object.
On each request, the client will check whether your certificate has expired; if it has, the client will attempt to reload the certificate before sending the request to the server.
**NOTE:** the client requires that your renewed certificate is in the same location as the old one.
Users may want to set up a cron job to facilitate auto-renewal of their certificate.
Passwords
~~~~~~~~~
Password-based authentication to limited portions of the GraceDB API has historically been available to partner astronomers who have an MOU with LIGO/Virgo.
The documentation for :py:class:`ligo.gracedb.rest.GraceDb` details how to provide these credentials to the client.
This authentication mechanism may be phased out in the future.
Response contents
-----------------
Most of the client methods return a :class:`httplib.HTTPResponse` object.
......@@ -207,8 +234,8 @@ There are a few tags which are used for exposing information (``lvem``, ``public
Special permissions are required to apply or remove these tags.
Other information
-----------------
Other methods
-------------
Additional methods are provided for managing signoffs, uploading EM observation data, and more.
These are not covered in detail here because they are rather specialized options.
See :ref:`api:API` for information about the client methods used for these actions.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment