pks-api-auth.html.md.erb

---
title: PKS API Authentication
owner: PKS
---

<strong><%= modified_date %></strong>

This topic describes how the Pivotal Container Service (PKS) API works with User Account and Authentication (UAA) to manage authentication and authorization in your PKS deployment.

##<a id='authenticating'></a> Authenticating PKS API Requests

Before users can log in and use the PKS CLI, you must configure PKS API access with UAA. For more information, see [Configuring PKS API Access](configure-api.html) with UAA.

You use the UAA Command Line Interface (UAAC) to target the UAA server and request an access token for the UAA admin user.
If your request is successful, the UAA server returns the access token.
The UAA admin access token authorizes you to make requests to the PKS API using the PKS CLI and grant cluster access to new or existing users. For more information, see [Grant Cluster Access](manage-users.html#cluster-access) in _Managing Users in PKS with UAA_.

When a user with cluster access logs in to the PKS CLI, the CLI requests an access token for the user from the UAA server.
If the request is successful, the UAA server returns an access token to the PKS CLI.
When the user runs PKS CLI commands, for example, `pks clusters`, the CLI sends the request to the PKS API server and includes the user's UAA token.

The PKS API sends a request to the UAA server to validate the user's token.
If the UAA server confirms that the token is valid, the PKS API uses the cluster information from the PKS broker to respond to the request.
For example, if the user runs `pks clusters`, the CLI returns a list of the clusters that the user is authorized to manage.

##<a id='routing'></a>Routing to the PKS API Control Plane VM

The PKS API server and the UAA server use different port numbers on the control plane VM.
For example, if your PKS API domain is `api.pks.example.com`, you can reach your PKS API and UAA servers at the following URLs:

<table>
  <tr>
    <th>Server</th>
    <th>URL</th>
  </tr>
  <tr>
    <td>PKS API</td>
    <td>api.pks.example.com:9021</td>
  </tr>
  <tr>
    <td>UAA</td>
    <td>api.pks.example.com:8443</td>
  </tr>
</table>

Refer to **Ops Manager > Pivotal Container Service > PKS API > API Hostname (FQDN)** for your PKS API domain.

Load balancer implementations differ by deployment environment.
For PKS deployments on GCP, AWS, or vSphere without NSX-T, you configure a load balancer to access 
the PKS API when you install the PKS tile.
For more information, see the [Configure External Load Balancer](installing-pks-vsphere.html#loadbalancer-pks-api) section of <em>Installing PKS</em> for 
your IaaS.

For procedures that describe routing to the PKS control plane VM, see the [Configure External Load Balancer](installing-pks-vsphere.html#loadbalancer-pks-api) section of <em>Installing PKS</em> for your IaaS.

For overview information about load balancers in PKS, see [Load Balancers in PKS Deployments without NSX-T](about-lb.html#without-nsx-t).