Specifying OpsRamp API Credentials
==================================
opcli requires OpsRamp REST API credentials to run its various commands.

Once you have `set up inbound OpsRamp API OAuth credentials <https://docs.opsramp.com/integrations/custom-integration/custom-integration/#configure-inbound-communication>`_ in a custom integration in the OpsRamp SaaS portal, the credentials you obtained there can be specified to your opcli commands in one of the following ways:

* Using command line arguments to speficy the credentials directly
* Using a YAML file (be default, environments.yml)

Credentials from command line arguments
---------------------------------------
To provide OpsRamp API credentials directly on the command line, use the following options:

.. code-block:: console

   --url URL             OpsRamp API URL (default: None)
   --client_id KEY       OpsRamp API Key (default: None)
   --client_secret SCRT  OpsRamp API Secret (default: None)
   --tenant TENANT       OpsRamp tenant ID (default: None)
   --partner PARTNER     OpsRamp partner ID (usually unnecessary - only needed for partner-level API calls) (default: None)
   --vtoken VTOKEN       OpsRamp webhook token (only used for webhookalerts command) (default: None)

Note that you only need to provide the attributes needed for the kind of API calls you are making. Therefore:

* If you are making an API call that does not require a partner id (which is not needed in most cases) you do not need to provide a partner value.
* If you are not doing webhook alert posts, you would not need to specify the vtoken value.
* If you are doing only webhook alert posts then you would not need client_id and client_secret.
* If you are using the environment for a bunch of different scenarios, there is no harm in having the extra values there for the cases where they are not needed.


Credentials from a YAML file
----------------------------
Instead of specifying credentials on the command line every time, you can have an environments.yml file that contains one or more named environment definitions, where each named environment provides a complete set of credentials.  This greatly simplifies running commands so that instead of specifying all of the credentials each time, you can just specify the environment by name, for example you can do this:

.. code-block:: console

   opcli getalerts --env example1 --count

instead of this:

.. code-block:: console

   opcli getalerts --url https://customer1name.api.opsramp.com --tenant tenantuuid1 --client_id abcdefg1234567 --client_secret abcdefg1234567 --count

By default, opcli expects environments.yml to be in the directory where you are running the command from. Optionally you can specify an explicit environments file path & name using the --envfile option.

The file must follow the following format, where the name attribute is the value you will specify to the --env option to define the URL and credentials you will use:


.. code-block:: YAML

   - name: example1
     url:  https://customer1name.api.opsramp.com
     partner: msp_nnnnn
     tenant: tenantuuid1
     client_id: abcdefg1234567
     client_secret: abcdefg1234567
     
   - name: example2
     url:  https://customer2name.api.opsramp.com
     partner: msp_nnnnn
     tenant: tenantuuid2
     client_id: abcdefg1234567
     client_secret: abcdefg1234567