Authenticate the CLI using an API token

You need to set up an API token to authenticate the Upsun CLI for any of the following tasks:

Running automated tasks on a CI system
Running automated tasks directly on app container, for example in a cron job

Before you begin

You might need the Upsun CLI to perform certain tasks. For example, you need the CLI to do the following:

Check the validity of an API token.
Load the CLI SSH certificate for non-CLI commands.

1. Create a machine user

To safely run automated tasks, first create machine users. Each machine user has its own Upsun account associated with a unique email address. You can grant them restrictive access permissions to handle specific automated tasks. For security purposes, create a machine user for each type of task you want to automate.

To create a machine user, follow these steps:

Using the CLI
In the Console

Run the following command using your machine user’s email address.
```
upsun user:add  EMAIL_ADDRESS --role viewer --role development:contributor
```
This sets your machine user as a viewer on your project and a contributor on development environments, with no access to other environment types. Note that you can further adjust user roles depending on your needs and each environment type.
In the email invitation, click Create account.
To create a Upsun account for the machine user, click Sign up and follow the instructions.

Go to your project and click Settings.
In the Project Settings menu, click Access.
Click Add.
Enter your machine user’s email address.
For each environment type, assign a role to your machine user and click Save.

2. Create an API token

Log in to the Console as your machine user.
Open the user menu (your name or profile picture).
Click My profile.
Go to the API tokens tab and click Create API token.
Enter a name for your API token and click Create API token.
To copy the API token to your clipboard, click Copy. Note that after you close the API tokens tab, you can’t display the API token again.
Store the API token somewhere secure on your computer.

Optional: check the validity of your API token

To check that your API token is valid, run the following command:

upsun auth:api-token-login

When prompted, enter your API token. You get output similar to this:

The API token is valid.
You are logged in.

For security reasons, rotate your API tokens regularly. When an API token is compromised, revoke it immediately.

3. Authenticate the CLI using your API token

After you create your API token, you can use it to do the following:

Allow a CI system to run automated tasks using the Upsun CLI.
Run automated tasks on an app container using the Upsun CLI, for example in a cron job.

Note that when running CLI commands in these cases, some operations might take time to complete. To avoid waiting for an operation to complete before moving on to the next one, use the --no-wait flag.

Authenticate in a CI system

You can allow your CI system to run automated tasks using the Upsun CLI. To do so, create an environment variable named UPSUN_CLI_TOKEN with your API token as its value. For more information, see your CI system’s official documentation.

To run SSH-based commands that aren’t specific to the Upsun CLI, see how to load the proper SSH certificate.

Authenticate in an environment

You can run automated tasks on an app container using the Upsun CLI. To do so, set your API token as a top-level environment variable.

Note

Once you add the token as an environment variable, anyone with SSH access can read its value. Make sure your machine user has only the necessary permissions.

Using the CLI
In the Console

Run the following command:

upsun variable:create \
   -e ENVIRONMENT_NAME \
   --level environment \
   --prefix 'env' \
   --name UPSUN_CLI_TOKEN \
   --sensitive true \
   --value 'API_TOKEN' \
   --inheritable false \
   --visible-build true \
   --no-interaction

Open the environment where you want to add the variable.
Click Settings.
Click Variables.
Click + Add variable.
In the Variable name field, enter env:UPSUN_CLI_TOKEN.
In the Value field, enter your API token.
Make sure the Available at runtime and Sensitive variable options are selected.
Click Add variable.

Then add a build hook to your app configuration to install the CLI as part of the build process.

.upsun/config.yaml

hooks:
  build: |
    set -e
    echo "Installing Upsun CLI"
    curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash

    echo "Testing Upsun CLI"
    upsun

You can now call the CLI from within the shell on the app container or in a cron job.

To run SSH-based commands that aren’t specific to the Upsun CLI, see how to load the proper SSH certificate.

You can set up a cron job on a specific type of environment. For example, to run the update source operation on your production environment, use the following cron job:

crons:
  update:
    spec: '0 0 * * *'
    commands:
      start: |
        if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
          upsun backup:create --yes --no-wait
          upsun source-operation:run update --no-wait --yes
        fi

Use the CLI SSH certificate for non-CLI commands

When you set a UPSUN_CLI_TOKEN environment variable, the CLI authentication isn’t complete until your run a CLI command or load the CLI SSH certificate.

For example, after setting a UPSUN_CLI_TOKEN environment variable, you might need to run ssh, git, rsync, or scp commands before you run any CLI commands.

In this case, to ensure all your commands work, load the CLI SSH certificate first. To do so, run the following command:

upsun ssh-cert:load --no-interaction

Integrated environments

Supported environments