Restrict Docker Endpoint Access by Team in Portainer

The problem: one login, every Docker environment

A new engineer logs into Portainer and sees the local Docker socket, the staging host, and the production host all in the same list. They mean to restart a staging container but select production by mistake. The damage is not caused by malice; it is caused by an access model that shows every endpoint to every user.

The useful takeaway is simple: do not give users direct endpoint access. Put users in teams, assign each team to the endpoints it needs, and grant the lowest role that works. In Portainer Community Edition, that means choosing between Administrator and Restricted User for each team-endpoint pairing.

How Portainer organizes access

Portainer groups access around four concepts. A user is a person who logs in. A team is a collection of users. An endpoint is a Docker environment Portainer manages, such as a local socket or a remote Docker host. A role is the permission level assigned to a team on an endpoint; Community Edition typically offers Administrator and Restricted User.

When you assign a team to an endpoint, every member of that team can see and act on that endpoint according to the role. Users not on any assigned team for an endpoint do not see it in their Portainer menu.

Worked example: limit a team to the staging endpoint

Perform these steps in the Portainer web interface as an administrator.

1. Open Settings > Teams and select Add team. Name it staging-ops and save.
2. Open Settings > Endpoints, select the staging endpoint, and edit its access control. Add the staging-ops team and choose Restricted User.
3. Create a user named alice and add her to the staging-ops team.
4. Log out and log in as alice.

Expected check: alice sees only the staging endpoint. She should not see production or the local socket in her endpoint list. If she can see more, review the endpoint's team assignments and remove any teams she should not inherit.

Risk: removing a team from an endpoint revokes access for every member immediately. There is no grace period.

Deploy a stack to the restricted endpoint

Once alice can see only staging, she can deploy a stack there without reaching other environments. Here is a minimal Compose file:

version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

In Portainer, select the staging endpoint, open Stacks, choose Add stack, and use the web editor to paste the file above. Name the stack staging-web and deploy it. The stack runs only on the endpoint alice is allowed to use.

Portainer also supports stacks from a Git repository with automatic redeployment through webhooks. Treat this as optional: if the repository token changes or the webhook URL is blocked, updates can pause without an obvious error in the UI.

Verification: open the stack in Portainer, confirm the container status is running, and check the container logs for the nginx startup message.

Limitations and how to check your work

• Community Edition role granularity is limited. You cannot grant permission for one stack but not another on the same endpoint.
• Deleting a team that is assigned to endpoints can leave orphaned access rules. Review endpoint assignments before removing a team.
• Service accounts and API keys let CI/CD pipelines call Portainer without personal passwords, but they inherit the role of the team or user they are tied to.

Practical check: after any team or endpoint change, log in as a non-admin member of that team and confirm the endpoint list and available actions match your intent.

Rollback

Because team and endpoint assignments change access state, you can undo them in the same screens where you created them. Remove the team from the endpoint, change the role back, or delete the user. No container data is lost; only access is revoked.

Closing

Start with one team per environment, assign only the endpoints that team needs, and audit the list every quarter. If you need stack-level permissions or LDAP synchronization, those features require Portainer Business Edition.