portainer-docs/admin/endpoints/add/api.md

Add an endpoint via the Portainer API

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

• A local endpoint using Docker socket communication.
• A remote endpoint using TCP communication.
• A remote endpoint using TCP communication secured via TLS.

{% hint style="info" %} 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. {% endhint %}

Preparation

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

http POST :9000/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 :9000/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

{% hint style="info" %} The JWT token is valid for 8 hours after it is generated. Once it expires, you will need to generate a new token. {% endhint %}

Adding an endpoint

Adding a local endpoint via the Docker socket

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

{% hint style="info" %} This example requires you to bind-mount the Docker socket when running Portainer. {% endhint %}

Run the following command:

http --form POST :9000/api/endpoints \
    "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE" \
    Name="test-local" EndpointCreationType=1

The response is a JSON object representing the endpoint:

{
    "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 endpoint

This query will create an endpoint 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.

{% hint style="info" %} The Docker API must be exposed on the provided IP address and port. To learn how to do this, refer to the Docker documentation. {% endhint %}

Run the following command:

http --form POST :9000/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 endpoint:

{
    "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 endpoint.

Adding a remote endpoint with TLS

This query will create an endpoint 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.

{% hint style="info" %} The Docker API must be exposed on the provided IP address and port. To learn how to do this, refer to the Docker documentation. {% endhint %}

Run the following command:

http --form POST :9000/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 endpoint:

{
    "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 endpoint.