Platform.sh User Documentation
Edit page

Authenticate the CLI using an API token

Back to home

On this page

Try for 30 days
Flexible, version-controlled infrastructure provisioning and development-to-production workflows
Activate your trial

You need to set up an API token to authenticate the Platform.sh 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 Anchor to this heading

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

1. Create a machine user Anchor to this heading

To safely run automated tasks, first create machine users. Each machine user has its own Platform.sh 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:

  1. Run the following command using your machine user’s email address.

    platform 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.

  2. In the email invitation, click Create account.

  3. To create a Platform.sh account for the machine user, click Sign up and follow the instructions.

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

2. Create an API token Anchor to this heading

  1. Log in to the Console as your machine user.
  2. Open the user menu (your name or profile picture).
  3. Click My profile.
  4. Go to the API tokens tab and click Create API token.
  5. Enter a name for your API token and click Create API token.
  6. 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.
  7. Store the API token somewhere secure on your computer.

Optional: check the validity of your API token Anchor to this heading

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

platform 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 Anchor to this heading

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

  • Allow a CI system to run automated tasks using the Platform.sh CLI.
  • Run automated tasks on an app container using the Platform.sh 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 Anchor to this heading

You can allow your CI system to run automated tasks using the Platform.sh CLI. To do so, create an environment variable named PLATFORMSH_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 Platform.sh CLI, see how to load the proper SSH certificate.

Authenticate in an environment Anchor to this heading

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

Run the following command:

platform variable:create \
   -e ENVIRONMENT_NAME \
   --level environment \
   --prefix 'env' \
   --name PLATFORMSH_CLI_TOKEN \
   --sensitive true \
   --value 'API_TOKEN' \
   --inheritable false \
   --visible-build true \
   --no-interaction
  1. Open the environment where you want to add the variable.
  2. Click Settings.
  3. Click Variables.
  4. Click + Add variable.
  5. In the Variable name field, enter env:PLATFORMSH_CLI_TOKEN.
  6. In the Value field, enter your API token.
  7. Make sure the Available at runtime and Sensitive variable options are selected.
  8. Click Add variable.

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

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

        echo "Testing Platform.sh CLI"
        platform

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 Platform.sh 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
                   platform backup:create --yes --no-wait
                   platform source-operation:run update --no-wait --yes
                fi

Use the CLI SSH certificate for non-CLI commands Anchor to this heading

When you set a PLATFORMSH_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 PLATFORMSH_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:

platform ssh-cert:load --no-interaction

Is this page helpful?