Using the API

This document describes how to use the Photon Controller API. It is a RESTful API.

Although the following examples use the cURL command-line tool, but you can use your favorite REST client. The examples also use the jq command-line tool to neatly format the responses from cURL: The tool is not required, but it aids in understanding the response.

The API

You can find the full documentation for the API from a running Photon Controller. Point your web browser at one of the following URLs:

• Authenticated: https://IP-ADDRESS/api
• Unauthenticated: http://IP-ADDRESS:9000/api

Here are a couple of tips to help you navigate the API:

Unauthenticated APIs

Two APIs are unauthenticated:

1. /v1/system/auth: This allows you to get information about how to contact Lightwave to get tokens.
2. /v1/system/available: This is meant for use by a load-balancer to determine whether the API is available.

Authorization

Not all users can use all APIs. See authentication for information on what is available to different users.

Tenant and Project scope

You may ask a question that seems simple: what API call lists all the VMs? Because Photon Controller is multi-tenant, there is no such API call. VMs are owned by a single tenant and contained in a project. Instead of querying for all VMs in the system, you can query for all the VMs in a single project.

Disks are similar and are scoped within a project. Hosts are scoped within a deployment.

API Port Numbers

We recommend accessing the API through a load-balancer. If you use the default HAProxy load balancer included with Photon Controller, the API may be on one of two ports:

Port 443: The port used when authentication is in place. Authentication is recommended for all deployments.

Port 9000: The port used when there is no authentication. Do not use this insecure method of connecting to the API in a production environment.

Authentication

Lightwave

Photon Controller uses Lightwave for authentication; see the instructions on how to configure Lightwave.

Tokens

Almost all API calls require authentication tokens. There are two ways to get the token:

1. Use the command-line client. We strongly recommend this method because the internal details of getting a token may change in the future.

2. Using the API. This is documented for completeness, but it is not recommended and subject to change. Use it at your own risk.

Using the API to obtain a token involves the following two-step process:

1. Use Photon Controller's /auth API to find out how to contact Lightwave. (This is one of two APIs that is unauthenticated.)

2. Present credentials to Lightwave's /openidconnect/token API to receive a token. In response you will receive an access token that you can present to the Photon Controller APIs. The token will expire after some time depending on your local policies. You will also receive a refresh token that will allow you to get more access tokens. The refresh token also expires, but it has a longer expiration time than the access token.

Getting a token via the command-line

You can use the photon command-line to create a new token. For example, assuming: you have a user named 'houdini' with passsword 'secret': (tokens have been trimmed for legibility)

% photon auth get-api-tokens -u 'houdini' -p 'secret'

Access Token:
eyJhb...pgwI

Refresh Token:
eyJhb...aVKE

Getting a token through the APIs

Querying the /auth API to find Lightwave

To find the instance of Lightwave being used by Photon Controller, query the /auth API. This API does not require authentication because it is required in order to authenticate.

Example:

% curl -k -s https://192.9.2.54/v1/system/auth | jq .
{
   "endpoint": "192.9.2.42"
}

Note that the port number is not included. Normally Lightwave will be on the standard HTTPS port, 443.

Querying Lightwave to get an access token

Please note that tokens are normally quite long, but we shorten them to make this text more clear. Also note that using a refresh token involves a slightly different process.

To get a token from Lightwave, you will do a POST to the /openidconnect/token API. The POST of the API will be a string that includes four things:

1. grant_type: password
2. username
3. password
4. scope: Use the string "openid offline_access rs_photon at_groups". Note that this is subject to change, and photon might be a different name in your release.

These are combined in a body in a way that looks similar to a URL with parameters. For example, if your username was 'houdini' and your password was 'secret', the body would look like:

grant_type=password&username=houdini&password=secret&scope=openid offline_access rs_photon at_groups'

Putting this into a POST request would look like this:

curl -k -s -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=password&username=ec-admin@example.com&password=Passw0rd!&scope=openid \ 
  offline_access rs_photon at_groups' \ https://192.9.2.42/openidconnect/token | jq .
{
  "access_token":  "eyJhbGc...NFD8k",
  "refresh_token": "eyJhbGc...uon-Q",
  "id_token": "eyJhbGc...0hyuo",
  "token_type": "Bearer",
  "expires_in": 7200
}

Using the token

Pass the token in the Authorization header, like this:

curl -s -k -H "Authorization: Bearer eyJhbGc...NFD8k" https://192.9.2.54/status | jq
{
  "components": [
    {
      "component": "PHOTON-CONTROLLER-CORE",
      "status": "READY",
    ... output trimmed ...
  "status": "READY"
}