Configuring PKS API Access

Page last updated:

Warning: Pivotal Container Service (PKS) v1.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy.
To stay up to date with the latest software and security updates, upgrade to a supported version.

This topic describes how to configure access to the Enterprise Pivotal Container Service (Enterprise PKS) API. See PKS API Authentication for more information about how the PKS API and UAA interact with your Enterprise PKS deployment.

Configure Access to the PKS API

  1. Locate your Ops Manager root CA certificate.

    • If Ops Manager generated your certificate, refer to the Retrieve the Ops Manager Root CA section of Managing Certificates with the Ops Manager API.
    • If you provided your own certificate, copy and paste the certificate you entered in the PKS API pane into a file.
  2. Target your UAA server by running the following command:

    uaac target https://PKS-API:8443 --ca-cert ROOT-CA-FILENAME


    • PKS-API is the fully qualified domain name (FQDN) you use to access the PKS API. You configured this URL in the PKS API section of Installing Enterprise PKS for your IaaS. For example, see Installing Enterprise PKS on vSphere.
    • ROOT-CA-FILENAME is the path for the certificate file you downloaded in a previous step. For example:
      $ uaac target --ca-cert my-cert.cert
      Including https:// in the PKS API URL is optional.
  3. To request a token from the UAA server run the following command:

    uaac token client get admin -s UAA-ADMIN-SECRET

    Where UAA-ADMIN-SECRET is your UAA admin secret. Refer to Ops Manager > Enterprise PKS > Credentials > Pks Uaa Management Admin Client to retrieve your UAA admin secret.

  4. Grant cluster access to new or existing users with UAA. For more information on granting cluster access to users or creating users, see the Grant Enterprise PKS Access to a User section of Managing Users in Enterprise PKS with UAA.

Log in to the PKS CLI as a User

For information about logging in to the PKS CLI as a user, see Logging in to Enterprise PKS.

Note: If you are creating a test environment, you can log in to the PKS CLI without creating a PKS CLI-specific user account. Instead, you can use the existing Admin account and its UAA password to log in to the PKS CLI. Refer to Ops Manager > Enterprise PKS > Credentials > Uaa Admin Password to retrieve your UAA Admin password and then follow the log in steps in Logging in to Enterprise PKS.

Log in to the PKS CLI as an Automated Client

On the command line, run the following command to log in to the PKS CLI as an automated client for a script or service:

pks login -a PKS-API --client-name CLIENT-NAME --client-secret CLIENT-SECRET --ca-cert CERTIFICATE-PATH


  • PKS-API is the domain name for the PKS API that you entered in Ops Manager > Enterprise PKS > PKS API > API Hostname (FQDN). For example,
  • CLIENT-NAME is your OAuth client ID.
  • CLIENT-SECRET is your OAuth client secret.
  • CERTIFICATE-PATH is the path to your root CA certificate. Provide the certificate to validate the PKS API certificate with SSL.

    For example:

    $ pks login -a \
    --client-name automated-client \
    --client-secret randomly-generated-secret \
    --ca-cert /var/tempest/workspaces/default/root_ca_certificate

Export PKS API Access Token

This procedure stores a PKS API access token as an environment variable that you can use when executing PKS API calls on the command line.

  1. To export your access token into an environment variable, run the following command:

    pks login -a PKS-API -u USER-ID -p 'PASSWORD' -k; \
    export YOUR_ACCESS_TOKEN=$(bosh int ~/.pks/creds.yml --path /access_token)


    • PKS-API is the FQDN of your PKS API endpoint. For example,
    • USER-ID is your Enterprise PKS user ID.
    • PASSWORD is your Enterprise PKS password.
    • YOUR_ACCESS_TOKEN is the name of your access token environment variable.

    For example:

    $ pks login -a -u alana -p 'psswrdabc123...!' -k; \
    export my_token=$(bosh int ~/.pks/creds.yml --path /access_token)

Please send any feedback you have to