ops-man-api.html.md.erb

---
title: Using the Ops Manager API
owner: Ops Manager
---

This topic explains how to access the Pivotal Operations Manager API,
and gives examples of how to use the API to perform some common Ops Manager operations.

## <a id='overview'></a> Overview

The Ops Manager API controls the Ops Manager VM directly, bypassing the Ops Manager UI.

Platform operators use the Ops Manager API to automate deployments, retrieve and manage credentials, and otherwise work with Ops Manager.
Tile Developers use the Ops Manager API to test and debug <%= vars.product_name  %> product tiles.

For more information about the Ops Manager API, see the [Ops Manager API](https://docs.pivotal.io/platform/opsman-api) documentation. Your Ops Manager serves a local copy of this documentation at `https://YOUR-OPS-MANAGER-FQDN/docs`.

### <a id='related'></a> Related Tools

For running Ops Manager operations from the command line or within shell scripts, the Ops Manager command-line interface (CLI) `om` is usually a better tool than the Ops Manager API.

For more information about `om`, see the [`om` repository](https://github.com/pivotal-cf/om).

For an overview of the Ops Manager API and the tools based on it, see [Using Ops Manager Programmatically and from the Command Line](./ops-man-api-cli.html).

## <a id='access'></a> Access the Ops Manager API

To access the Ops Manager API, you must authenticate to the Ops Manager User Account and Authentication (UAA) server and log in as described below.

For more information about UAA, see [User Account and Authentication (UAA) Server](../concepts/architecture/uaa.html).

### <a id='uaa'></a>Install the UAAC

If you haven't already, install the UAA Command Line Interface (UAAC) by running the following command from a terminal window:

```
gem install cf-uaac
```

### <a id='token'></a>Retrieve an Authorization Token

Every call to the Ops Manager API must include an authorization token that is acceptable to the Ops Manager UAA.

How you retrieve this token depends on whether your Ops Manager user store is an internal IaaS component or an external server.  With an internal UAA, the procedure depends on which IaaS you are on.

To retrieve your authorization token, perform the procedure below that corresponds to your Ops Man UAA location and IaaS.

#### <a id='vsphere'></a> Internal UAA on vSphere

To log in to the Ops Manager VM with SSH in vSphere, you need the public SSH key that imports the <%= vars.product_name %> `.ova` or `.ovf` file into your virtualization system.

You set the public SSH key in the **Public SSH Key** field of the **Customize template** screen when you deployed Ops Manager. For more information, see [Deploy Ops Manager](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/vsphere/deploy.html#deploy).

To retrieve the authorization token from internal UAA on vSphere, do the following:

1. SSH onto the Ops Manager VM:

    ```
    ssh ubuntu@OPS-MANAGER-FQDN
    ```

    Where `OPS-MANAGER-FQDN` is the fully qualified domain name of Ops Manager.

    For example:

    <pre class='terminal'>
    $ ssh ubuntu@my-opsmanager<span>.</span>example.com
    </pre>

1. When prompted, enter the public SSH key.

1. Proceed to [Log in to Ops Manager](#opsman_login).

#### <a id='aws'></a> Internal UAA on AWS, Azure, or OpenStack

1. Locate the Ops Manager FQDN on the AWS **EC2 instances** page, Azure **Virtual machines** page, or the OpenStack **Access & Security** page.

1. Run `chmod 600` to change the permissions on the `.pem` file to be more restrictive:

    ```
    chmod 600 OPS-MGR-PEM
    ```
    Where `OPS-MGR-PEM` is the public key from the keypair used when creating the Ops Manager VM.

    For example:

    <pre class="terminal">$ chmod 600 ops_mgr.pem</pre>

1. Run `ssh -i OPS-MGR-PEM ubuntu@OPS-MANAGER-FQDN` to SSH into the Ops Manager VM:

    ```
    ssh -i ops_mgr.pem ubuntu@OPS-MANAGER-FQDN
    ```
    Where:
    * `OPS-MGR-PEM` is the public key from the keypair used when creating the Ops Manager VM.
    * `OPS-MANAGER-FQDN` is the fully qualified domain name of your Ops Manager.

    For example:

    <pre class="terminal">$ ssh -i ops_mgr.pem ubuntu@my-opsmanager.example.com</pre>

1. Proceed to [Log in to Ops Manager](#opsman_login).

#### <a id='gcp'></a> Internal UAA on GCP

1. Confirm that you have installed the gcloud CLI. If you do not have the gcloud CLI, see [the Google Cloud Platform documentation](https://cloud.google.com/sdk/gcloud/#downloading_gcloud):

1. To configure your Google Cloud Platform project, run the following command:

    ```
    $ gcloud config set project MY-PROJECT
    ```
    Where `PROJECT` is the name of your GCP project.

    For example:

    <pre class="terminal">$ gcloud config set project gcp</pre>

1. Run the following command:

    ```
    gcloud auth login MY-GCP-ACCOUNT
    ```
    Where `MY-GCP-ACCOUNT` is your GCP account ID.

    For example:

    <pre class="terminal">$ gcloud auth login user<span>@</span>example.com</pre>

1. Run the following command:

    ```
    gcloud compute ssh MY-INSTANCE --zone MY-ZONE
    ```
    Where:
    * `MY-INSTANCE` is your Ops Manager VM instance.
    * `MY-ZONE` is the zone where your Ops Manager VM is running.

    For example:

    <pre class="terminal">$ gcloud compute ssh om-<%= vars.product_name_lc %>-1a --zone us-central1-b</pre>

1. Switch to the `ubuntu` user by running the following command:

    ```
    sudo su - ubuntu
    ```

1. Proceed to [Log in to Ops Manager](#opsman_login).

#### <a id='external-idp'></a> External UAA

If you configured your Ops Manager for an external Identity Provider with SAML or LDAP, you do not need any IaaS-specific setup. You can proceed to [Log in to Ops Manager](#opsman_login).

### <a id='opsman_login'></a> Log in to Ops Manager

To log in to the Ops Manager VM and retrieve your token, do the following:

1. Use the UAAC to target your Ops Manager UAA server:

    ```
    uaac target https://OPS-MAN-FQDN/uaa
    ```

    Where `OPS-MANAGER-FQDN` is the fully qualified domain name of Ops Manager.

    For example:

    <pre class="terminal">$ target https://my-opsmanager.example.com/uaa</pre>

1. Depending on whether your Ops Manager UAA is internal or external, run a command to retrieve your UAA token and respond to the authentication prompts as follows:
  * **Internal**

    	```
      uaac token owner get
    	Client ID: opsman
    	Client secret: [Leave Blank]
    	User name: OPS-MAN-USERNAME
    	Password: OPS-MAN-PASSWORD
    	```
      Where `OPS-MAN-USERNAME` and `OPS-MAN-PASSWORD` are the credentials that you use to log in to the Ops Manager web interface.
      For example:
      <pre class="terminal">
        $ uaac token owner get
        Client ID: opsman
        Client secret:
        User name: my-opsman-username
        Password: my-opsman-password
      </pre>
  * **External**

    	```
      uaac token sso get
    	Client ID: opsman
    	Client secret: [Leave Blank]
    	Passcode: OPS-MAN-PASSCODE
    	```
      Where `OPS-MAN-PASSCODE` is the value you retrieve from `https://OPS-MAN-FQDN/uaa/passcode`.
      For example:
      <pre class="terminal">
        $ uaac token sso get
        Client ID: opsman
        Client secret:
        Password: my-opsman-passcode
      </pre>

If authentication is successful, the UAAC displays the following message: `Successfully fetched token via owner password grant.`

### <a id='run-commands'></a>Run API Commands

To run any Ops Manager API command, you pass your authorization token to the API command endpoint in a header that follows the format `Authorization: Bearer YOUR-ACCESS-TOKEN`.

If you are calling Ops Manager API commands from the command line, the machine that you can be logged into depends on the location of your Ops Manager UAA, as follows:

  * **Internal**: You must run Ops Manager API commands from the Ops Manager VM.
  * **External**: You may run commands from your local machine.

#### <a id='test-command'></a>API Access Test

The following procedure tests whether you can access the Ops Manager API from the command line by retrieving a list of deployed products:

1. List your tokens by running the following command:

    ```
    uaac contexts
    ```
    In the command output, locate the entry for your Ops Manager FQDN. Under `client_id: opsman`, record the value for `access_token`.

1. Use the `GET /api/v0/deployed/products` endpoint to retrieve a list of deployed products:

    ```
    curl "https://OPS-MAN-FQDN/api/v0/deployed/products" \
  	    -X GET \
  	    -H "Authorization: Bearer UAA-ACCESS-TOKEN
    ```
    Where `UAA-ACCESS-TOKEN` is the access token recorded in the previous step.

    The command output should look like the following:
  	<pre class="terminal">
  	$ curl "http<span>s:</span>my-opsmanager.example.com/api/v0/deployed/products" \
  	    -X GET \
  	    -H "Authorization: Bearer my-access-token"
  	[{"installation\_name":"p-bosh","guid":"p-bosh
  	-00000000000000000000","type":"p-
  	bosh","product\_version":"1.10.0.
  	0"},{"installation\_name":"cf-
  	00000000000000000000","guid":"cf-0000000000000
  	0000000","type":"cf","product\_version":"1.10.0"}]
  	</pre>

## <a id="api-procedures"></a>Example Ops Manager API Procedures

The following procedures illustrate how to test API calls from the command line. If you are a developer writing deployment or test routines in programming languages, these procedures show how you might test the routines line-by-line while building them.

The Ops Manager command-line interface (CLI) [`om`](./ops-man-api-cli.html#om) is usually a better tool than the Ops Manager API for running Ops Manager operations directly from the command-line or within shell scripts.

These methods are intended for advanced <%= vars.product_name %> operators and administrators.

### <a id="configure-bosh"></a>Configure the BOSH Director

The following procedure configures the BOSH Director for your IaaS using the Ops Manager API.

Pivotal recommends that beginning users configure the BOSH Director through the Ops Manager UI, which provides context and explanations for each option. For information about configuring the BOSH Director tile in the Ops Manager UI, see one of the following:

* AWS ([Terraform](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/aws/config-terraform.html) | [manual](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/aws/config-manual.html))
* Azure ([Terraform](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/azure/config-terraform.html) | [manual](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/azure/config-manual.html))
* GCP ([Terraform](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/gcp/config-terraform.html) | [manual](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/gcp/config-manual.html))
* [OpenStack](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/openstack/config.html)
* [vSphere](/platform/ops-manager/<%= vars.current_major_version.sub('.', '-') %>/vsphere/config.html)

To configure the BOSH Director with the Ops Manager API, do the following:

1. Access the Ops Manager API by following the procedure in <a href="#access">Access the Ops Manager API</a> procedure above.</li>

1. To perform initial setup, enter a `POST` request to the Ops Man API `setup` endpoint, passing metadata to the `-d` flag:

    ```
    curl "https://YOUR-OPS-MANAGER-URL.com/api/v0/setup" \
      -X POST \
      -H "Content-Type: application/json" \
      -d '{ "setup": {
      "decryption_passphrase": "PASSPHRASE",
      "decryption_passphrase_confirmation":"PASSPHRASE",
      "eula_accepted": "EULA-STATUS",
      "identity_provider": "IDP-LOCATION",
      "admin_user_name": "ADMIN-USERNAME",
      "admin_password": "ADMIN-PASSWORD",
      "admin_password_confirmation": "ADMIN-PASSWORD",
      "http_proxy": HTTP-PROXY,
      "https_proxy": HTTPS-PROXY,
      "no_proxy": "127.0.0.1"
    ```
    Where:
    * `PASSPHRASE` is your deployment's decryption passphrase
    * `EULA-STATUS` is your EULA status
    * `IDP-LOCATION` is your identity provider location, `internal` or `external`
    * `ADMIN-USERNAME`is your Ops Manager admin username
    * `ADMIN-PASSWORD`is your Ops Manager admin password
    * `HTTP-PROXY` is your HTTP proxy, if applicable
    * `HTTPS-PROXY` is your HTTPS proxy, if applicable

    For example:
    <pre class="terminal">
    $ curl "http<span>s:</span>//my-opsman.example.com/api/v0/setup" \
      -X POST \
      -H "Content-Type: application/json" \
      -d '{ "setup": {
      "decryption\_passphrase": "my-passphrase",
      "decryption\_passphrase\_confirmation":"my-passphrase",
      "eula\_accepted": "true",
      "identity\_provider": "internal",
      "admin\_user\_name": "my-username",
      "admin\_password": "my-password",
      "admin\_password\_confirmation": "my-password",
      "http\_proxy": "htt<span>p:</span>//myproxy.example.com",
      "https\_proxy": "http<span>s:</span>//myproxy.example.com",
      "no\_proxy": "127.0.0.1"
    } }'
    </pre>
 	<p class="note"><strong>Note</strong>: You do not need to specify UAA or other authentication details on a first-time deploy. Making the <code>setup</code> request automatically creates a UAA client when it completes successfully. If you specify a UAA client for a first-time deployment, the deployment will fail.</p>

1. A <code>200 OK</code> response appears.</li>

1. After the successful response, a UAA client with the metadata you specified is created and launched. Ops Manager users can authenticate with UAAC, and if they have a pre-created client they can target UAAC with the client name and password. For more information on pre-created clients, see <a href="./opsman-users.html">Creating and Managing Ops Manager User and Client Accounts</a>.

1. Send an HTTP `PUT` request to the `api/v0/staged/director/properties` endpoint to configure your IaaS and BOSH Director.
There are many configuration parameters available to customize your BOSH Director. All the commands are IaaS-agnostic except the IaaS configuration key. Missing required fields should cause an error.
For more information about configuring the BOSH Director, see <a href="http://docs.pivotal.io/pivotalcf/2-5/opsman-api/#fetching-director-iaas-and-security-properties-experimental">Fetching Director, IaaS, and Security Properties</a>.

1. Send an HTTP `POST` request to the `api/v0/staged/director/availability_zones` endpoint to create Availability Zones (AZs) for your product.
<p class="note"><strong>Note</strong>: The <code>create-azs</code> endpoint is optional for Azure-based deployments, because you cannot manually configure Azure AZs.</p>

1. Send an HTTP `PUT` request to the `api/v0/staged/director/networks` endpoint to create networking rules for the deployment.
Specify whether or not to use ICMP checks by setting the `icmp_checks_enabled` parameter to `true` or `false`.

1. Send an HTTP `PUT` request to the `api/v0/staged/director/network_and_az` endpoint to assign a singleton AZ and a network where your BOSH Director will be located.

1. You must update the BOSH Director's resource configuration settings before deploying BOSH. To update the resource config, do the following:

  1. Send a `GET` request to `api/v0/staged/products` to find your Director's GUID.
	1. Use the following HTTP request to list all jobs on the Director: `GET api/v0/staged/products/:BOSH-DIRECTOR-GUID/jobs`.
	1. Use the following HTTP request to update the resource config of each job on the BOSH Director: `PUT api/v0/staged/products/:BOSH-DIRECTOR-GUID/jobs/:JOB-GUID/resource_config`.

### <a id="configure-product"></a>Configure a Product

The following procedure uploads, stages, and configures a product tile using the Ops Manager API:

1. Upload or import the product into Ops Manager.
  1. Send an HTTP `POST` request to the `api/v0/available_products` endpoint to upload the product.
  1. Send an HTTP `GET` request to the `api/v0/available_products` endpoint to list the names of available products.
  1. In the output list from `available_products`, find the product you uploaded by referencing its name and version.
  1. Send an HTTP `POST` request to the `/api/v0/staged/products` endpoint to add the uploaded product to Ops Manager.
1. Send an HTTP `GET` request to the `api/v0/staged_products` endpoint to confirm that the product is staged for deployment in Ops Manager and display the product GUID.
1. Send an HTTP `PUT` request to the `PUT /api/v0/staged/products/:PRODUCT-GUID/networks_and_azs` to assign availability zones (AZs) and networks to the product.
    Where `PRODUCT-GUID` is the product GUID.
1. Send an HTTP `PUT` request to the `/api/v0/staged/products/:PRODUCT-GUID/properties` endpoint to update the product's properties.
    Where `PRODUCT-GUID` is the product GUID.
1. Send an HTTP `PUT` request to the `/api/v0/staged/products/:PRODUCT-GUID/syslog_configuration` endpoint to configure syslog for the product.
    Where `PRODUCT-GUID` is the product GUID.
1. Update the product's resource configuration by doing the following:
   1. Send an HTTP `GET` request to the `api/v0/staged/products/:PRODUCT-GUID/jobs` endpoint to list all jobs on a product and display the GUID for each job.
      Where `PRODUCT-GUID` is the product GUID.
   1. Send an HTTP `PUT` request to the `api/v0/staged/products/:PRODUCT-GUID/jobs/:JOB-GUID/resource_config` endpoint to update the resource config for a particular job.
      Where:
      * `PRODUCT-GUID` is the product GUID.
      * `JOB-GUID` is the job GUID.

### <a id="upgrade-opsman"></a>Upgrade Ops Manager

The following procedure upgrades Ops Manager using the Ops Manager API:

#### <a id="prereqs"></a>Prerequisites

Before you upgrade Ops Manager with the Ops Manager API, you must have the following:

 * Two versions of Ops Manager: an existing deployment and a new deployment of a later version. The new deployment cannot be configured in any way.
 * DNS information for the existing deployment of Ops Manager

#### <a id="upgrade"></a>Procedure

Follow this procedure to upgrade your Ops Manager:

1. Send an HTTP `GET` request to the `/api/v0/installation_asset_collection` endpoint of your old Ops Manager to export your existing installation data.
1. Send an HTTP `POST` request to the `/api/v0/installation_asset_collection` endpoint of your new Ops Manager to import your installation data to the new deployment.
1. Send an HTTP `POST` request to the `/api/v0/installations` endpoint of your new Ops Manager to trigger a new installation process.
1. Test the new deployment.
1. (Optional) Delete the old deployment.