Add an environment via the Portainer API

Portainer's API lets you perform the same actions as via the Portainer UI, including adding new environments. This article explains how to add the following types of environments via the API:

• A local environment using Docker socket communication.

• A remote environment using TCP communication.

• A remote environment using TCP communication secured via TLS.

The examples in this article use httpie to make HTTP calls from the command line to the Portainer API. Feel free to replace httpie with your preferred method.

Preparation

After deploying Portainer, you'll need to initialize your admin user. First, initialize the admin password:

http POST https://my-portainer-server:9443/api/users/admin/init Username="admin" Password="adminpassword"

Now, use the admin account to authenticate against the API. Generate an authorization token for your username. This token will provide you with the same permissions as the user who generated it.

http POST https://my-portainer-server:9443/api/auth Username="admin" Password="adminpassword"

The response is a JSON object containing the JWT token inside the jwt field. Make a note of this token. You'll use it in the authorization header when making API calls.

{
  "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE"
}

The authorization header value must take the form Bearer JWT_TOKEN. Using the above token as an example, the value would look like this:

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE

The JWT token is valid for 8 hours after it is generated. Once it expires, you will need to generate a new token.

Adding an environment

Adding a local environment via the Docker socket

This query will create an environment called test-local and will use the Docker socket to communicate with your environment.

This example requires you to bind-mount the Docker socket when running Portainer.

Run the following command:

http --form POST https://my-portainer-server:9443/api/endpoints \
    "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE" \
    Name="test-local" EndpointCreationType=1

The response is a JSON object representing the environment:

{
    "AuthorizedTeams": [], 
    "AuthorizedUsers": [], 
    "Extensions": [], 
    "GroupId": 1, 
    "Id": 1, 
    "Name": "test-local", 
    "PublicURL": "",
    "Type": 1,
    "TLSConfig": {
        "TLS": false, 
        "TLSSkipVerify": false
    }, 
    "Type": 1, 
    "URL": "unix:///var/run/docker.sock"
}

Make a note of the Id value. It will be used to execute queries against the Docker Engine for the endpoint.

Adding a remote environment

This query will create an environment called test-remote. It will communicate with your environment over TCP using the IP address 10.0.7.10 and port 2375. Make sure you replace the example values with your own IP address and port.

The Docker API must be exposed on the provided IP address and port. To learn how to do this, refer to the Docker documentation.

Run the following command:

http --form POST https://my-portainer-server:9443/api/endpoints \
    "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE" \
    Name="test-remote" URL="tcp://10.0.7.10:2375" EndpointCreationType=1

The response is a JSON object representing the environment:

{
    "AuthorizedTeams": [], 
    "AuthorizedUsers": [], 
    "Extensions": [], 
    "GroupId": 1, 
    "Id": 1, 
    "Type": 1,
    "Name": "test-remote", 
    "PublicURL": "", 
    "TLSConfig": {
        "TLS": false, 
        "TLSSkipVerify": false
    }, 
    "Type": 1, 
    "URL": "tcp://10.0.7.10:2375"
}

Take a note of the Id value. It will be used to execute queries against the Docker Engine for the environment.

Adding a remote environment with TLS

This query will create an environment called test-remote-tls. It will communicate with your environment over TCP (secured with TLS) using the IP address 10.0.7.10 and port 2376. Make sure you replace the example values with your own IP address and port.

The Docker API must be exposed on the provided IP address and port. To learn how to do this, refer to the Docker documentation.

Run the following command:

http --form POST https://my-portainer-server:9443/api/endpoints \
    "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE" \
    Name="test-remote-tls" URL="tcp://10.0.7.10:2376" EndpointCreationType=1 TLS="true" TLSCACertFile@/path/to/ca.pem TLSCertFile@/path/to/cert.pem TLSKeyFile@/path/to/key.pem

The response is a JSON object representing the environment:

{
    "AuthorizedTeams": [], 
    "AuthorizedUsers": [], 
    "Extensions": [], 
    "GroupId": 1, 
    "Id": 1, 
    "Type": 1,
    "Name": "test-remote-tls", 
    "PublicURL": "", 
    "TLSConfig": {
        "TLS": true, 
        "TLSCACert": "/data/tls/1/ca.pem", 
        "TLSCert": "/data/tls/1/cert.pem", 
        "TLSKey": "/data/tls/1/key.pem", 
        "TLSSkipVerify": false
    }, 
    "Type": 1, 
    "URL": "tcp://10.0.7.10:2376"
}

Make a note of the Id value. It will be used to execute queries against the Docker Engine for the environment.