Portainer

Portainer Users API

Manage users

Documentation GitHub OpenAPI

Operations 13

GET /users List users #

POST /users Create a new user #

DELETE /users/{id} Remove a user #

GET /users/{id} Inspect a user #

PUT /users/{id} Update a user #

GET /users/{id}/memberships Inspect a user memberships #

PUT /users/{id}/passwd Update password for a user #

GET /users/{id}/tokens Get all API keys for a user #

POST /users/{id}/tokens Generate an API key for a user #

DELETE /users/{id}/tokens/{keyID} Remove an api-key associated to a user #

GET /users/admin/check Check administrator account existence #

POST /users/admin/init Initialize administrator account #

GET /users/me Inspect the current user user #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/portainer-users-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  contact:
    email: info@portainer.io
  description: Portainer API is an HTTP API served by Portainer.
  license:
    name: zlib
    url: https://github.com/portainer/portainer/blob/develop/LICENSE
  title: PortainerCE Users API
  version: 2.39.1
servers:
- url: /api
tags:
- description: Manage users
  name: Users
paths:
  /users:
    get:
      description: 'List Portainer users.

        Non-administrator users will only be able to list other non-administrator user accounts.

        User passwords are filtered out, and should never be accessible.

        **Access policy**: restricted'
      operationId: UserList
      parameters:
      - description: Identifier of the environment(endpoint) that will be used to filter the authorized users
        in: query
        name: environmentId
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/portainer.User'
                type: array
        '400':
          description: Invalid request
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: List users
      tags:
      - Users
    post:
      description: 'Create a new Portainer user.

        Only administrators can create users.

        **Access policy**: restricted'
      operationId: UserCreate
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/portainer.User'
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '409':
          description: User already exists
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Create a new user
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/users.userCreatePayload'
        description: User details
        required: true
  /users/{id}:
    delete:
      description: 'Remove a user.

        **Access policy**: administrator'
      operationId: UserDelete
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: User not found
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Remove a user
      tags:
      - Users
    get:
      description: 'Retrieve details about a user.

        User passwords are filtered out, and should never be accessible.

        **Access policy**: authenticated'
      operationId: UserInspect
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/portainer.User'
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: User not found
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Inspect a user
      tags:
      - Users
    put:
      description: 'Update user details. A regular user account can only update his details.

        A regular user account cannot change their username or role.

        **Access policy**: authenticated'
      operationId: UserUpdate
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/portainer.User'
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: User not found
        '409':
          description: Username already exist
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Update a user
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/users.userUpdatePayload'
        description: User details
        required: true
  /users/{id}/memberships:
    get:
      description: 'Inspect a user memberships.

        **Access policy**: restricted'
      operationId: UserMembershipsInspect
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/portainer.TeamMembership'
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Inspect a user memberships
      tags:
      - Users
  /users/{id}/passwd:
    put:
      description: 'Update password for the specified user.

        **Access policy**: authenticated'
      operationId: UserUpdatePassword
      parameters:
      - description: identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: User not found
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Update password for a user
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/users.userUpdatePasswordPayload'
        description: details
        required: true
  /users/{id}/tokens:
    get:
      description: 'Gets all API keys for a user.

        Only the calling user or admin can retrieve api-keys.

        **Access policy**: authenticated'
      operationId: UserGetAPIKeys
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/portainer.APIKey'
                type: array
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: User not found
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Get all API keys for a user
      tags:
      - Users
    post:
      description: 'Generates an API key for a user.

        Only the calling user can generate a token for themselves.

        Password is required only for internal authentication.

        **Access policy**: restricted'
      operationId: UserGenerateAPIKey
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/users.accessTokenResponse'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Permission denied
        '404':
          description: User not found
        '500':
          description: Server error
      security:
      - jwt: []
      summary: Generate an API key for a user
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/users.userAccessTokenCreatePayload'
        description: details
        required: true
  /users/{id}/tokens/{keyID}:
    delete:
      description: 'Remove an api-key associated to a user..

        Only the calling user or admin can remove api-key.

        **Access policy**: authenticated'
      operationId: UserRemoveAPIKey
      parameters:
      - description: User identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: Api Key identifier
        in: path
        name: keyID
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: Not found
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Remove an api-key associated to a user
      tags:
      - Users
  /users/admin/check:
    get:
      description: 'Check if an administrator account exists in the database.

        **Access policy**: public'
      operationId: UserAdminCheck
      responses:
        '204':
          description: Success
        '404':
          description: User not found
      summary: Check administrator account existence
      tags:
      - Users
  /users/admin/init:
    post:
      description: 'Initialize the ''admin'' user account.

        **Access policy**: public'
      operationId: UserAdminInit
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/portainer.User'
        '400':
          description: Invalid request
        '409':
          description: Admin user already initialized
        '500':
          description: Server error
      summary: Initialize administrator account
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/users.adminInitPayload'
        description: User details
        required: true
  /users/me:
    get:
      description: 'Retrieve details about the current user.

        User passwords are filtered out, and should never be accessible.

        **Access policy**: authenticated'
      operationId: CurrentUserInspect
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/portainer.User'
        '400':
          description: Invalid request
        '403':
          description: Permission denied
        '404':
          description: User not found
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Inspect the current user user
      tags:
      - Users
components:
  schemas:
    users.userUpdatePayload:
      properties:
        NewPassword:
          example: asfj2emv
          type: string
        Password:
          example: cg9Wgky3
          type: string
        Role:
          description: User role (1 for administrator account and 2 for regular account)
          enum:
          - 1
          - 2
          example: 2
          type: integer
        Theme:
          $ref: '#/components/schemas/users.themePayload'
        UseCache:
          example: true
          type: boolean
        Username:
          example: bob
          type: string
      required:
      - NewPassword
      - Password
      - Role
      - UseCache
      - Username
      type: object
    users.userUpdatePasswordPayload:
      properties:
        NewPassword:
          description: New Password
          example: new_passwd
          type: string
        Password:
          description: Current Password
          example: passwd
          type: string
      required:
      - NewPassword
      - Password
      type: object
    users.userAccessTokenCreatePayload:
      properties:
        description:
          example: github-api-key
          type: string
        password:
          example: password
          type: string
      required:
      - description
      - password
      type: object
    users.accessTokenResponse:
      properties:
        apiKey:
          $ref: '#/components/schemas/portainer.APIKey'
        rawAPIKey:
          type: string
      type: object
    portainer.User:
      properties:
        EndpointAuthorizations:
          allOf:
          - $ref: '#/components/schemas/portainer.EndpointAuthorizations'
          description: Deprecated in DBVersion == 25
        Id:
          description: User Identifier
          example: 1
          type: integer
        PortainerAuthorizations:
          allOf:
          - $ref: '#/components/schemas/portainer.Authorizations'
          description: Deprecated in DBVersion == 25
        Role:
          allOf:
          - $ref: '#/components/schemas/portainer.UserRole'
          description: User role (1 for administrator account and 2 for regular account)
          example: 1
        ThemeSettings:
          $ref: '#/components/schemas/portainer.UserThemeSettings'
        TokenIssueAt:
          example: 1
          type: integer
        UseCache:
          example: true
          type: boolean
        UserTheme:
          description: Deprecated
          example: dark
          type: string
        Username:
          example: bob
          type: string
      type: object
    users.userCreatePayload:
      properties:
        Password:
          example: cg9Wgky3
          type: string
        Role:
          description: User role (1 for administrator account and 2 for regular account)
          enum:
          - 1
          - 2
          example: 2
          type: integer
        Username:
          example: bob
          type: string
      required:
      - Password
      - Role
      - Username
      type: object
    portainer.TeamMembership:
      properties:
        Id:
          description: Membership Identifier
          example: 1
          type: integer
        Role:
          allOf:
          - $ref: '#/components/schemas/portainer.MembershipRole'
          description: Team role (1 for team leader and 2 for team member)
          example: 1
        TeamID:
          description: Team identifier
          example: 1
          type: integer
        UserID:
          description: User identifier
          example: 1
          type: integer
      type: object
    users.adminInitPayload:
      properties:
        Password:
          description: Password for the admin user
          example: admin-password
          type: string
        Username:
          description: Username for the admin user
          example: admin
          type: string
      required:
      - Password
      - Username
      type: object
    users.themePayload:
      properties:
        color:
          description: Color represents the color theme of the UI
          enum:
          - dark
          - light
          - highcontrast
          - auto
          example: dark
          type: string
      type: object
    portainer.Authorizations:
      additionalProperties:
        type: boolean
      type: object
    portainer.UserThemeSettings:
      properties:
        color:
          description: Color represents the color theme of the UI
          enum:
          - dark
          - light
          - highcontrast
          - auto
          example: dark
          type: string
      type: object
    portainer.UserRole:
      enum:
      - 0
      - 1
      - 2
      type: integer
      x-enum-varnames:
      - _
      - AdministratorRole
      - StandardUserRole
    portainer.MembershipRole:
      enum:
      - 0
      - 1
      - 2
      type: integer
      x-enum-varnames:
      - _
      - TeamLeader
      - TeamMember
    portainer.EndpointAuthorizations:
      additionalProperties:
        $ref: '#/components/schemas/portainer.Authorizations'
      type: object
    portainer.APIKey:
      properties:
        dateCreated:
          description: Unix timestamp (UTC) when the API key was created
          type: integer
        description:
          example: portainer-api-key
          type: string
        digest:
          description: Digest represents SHA256 hash of the raw API key
          type: string
        id:
          example: 1
          type: integer
        lastUsed:
          description: Unix timestamp (UTC) when the API key was last used
          type: integer
        prefix:
          description: API key identifier (7 char prefix)
          type: string
        userId:
          example: 1
          type: integer
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-KEY
      type: apiKey
    jwt:
      in: header
      name: Authorization
      type: apiKey