# List users


[API catalog](/reference/api/) · [Docker Hub overview](/reference/api/hub/latest/) · [Product manual](https://docs.docker.com/docker-hub/) · [OpenAPI specification](/reference/api/hub/latest.yaml)

API version: 2-beta



`GET /v2/scim/2.0/Users`

Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results.

**Sorting:**

Sorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters.

The `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are "ascending" and "descending".

**Filtering:**

You can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.

Supported operators are listed below.

- `eq` equal
- `ne` not equal
- `co` contains
- `sw` starts with
- `and` Logical "and"
- `or` Logical "or"
- `not` "Not" function
- `()` Precedence grouping


## Connection and access

[API connection and authentication guidance](/reference/api/hub/latest/#authentication)


Server: `https://hub.docker.com`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
[
  {
    "scimToken": []
  }
]
```
## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request GET \
  --header "Authorization: Bearer ${SCIM_TOKEN}" \
  --header 'Accept: application/scim+json' \
  'https://hub.docker.com/v2/scim/2.0/Users?startIndex=1&count=10&filter=userName+eq+%22jon.snow%40docker.com%22&attributes=userName%2CdisplayName&sortBy=userName'
```

## Parameters

### startIndex

Location: query. Required: no.

One-based index of the first result to return.

```json
{
  "description": "One-based index of the first result to return.",
  "example": 1,
  "in": "query",
  "name": "startIndex",
  "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/0",
  "schema": {
    "minimum": 1,
    "type": "integer"
  }
}
```

### count

Location: query. Required: no.

Maximum number of results to return.

```json
{
  "description": "Maximum number of results to return.",
  "example": 10,
  "in": "query",
  "name": "count",
  "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/1",
  "schema": {
    "maximum": 200,
    "minimum": 1,
    "type": "integer"
  }
}
```

### filter

Location: query. Required: no.

SCIM filter expression used to select users.

```json
{
  "description": "SCIM filter expression used to select users.",
  "example": "userName eq \"jon.snow@docker.com\"",
  "in": "query",
  "name": "filter",
  "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/2",
  "schema": {
    "type": "string"
  }
}
```

### attributes

Location: query. Required: no.

Comma delimited list of attributes to limit to in the response.

```json
{
  "description": "Comma delimited list of attributes to limit to in the response.",
  "example": "userName,displayName",
  "in": "query",
  "name": "attributes",
  "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/3",
  "schema": {
    "type": "string"
  }
}
```

### sortOrder

Location: query. Required: no.

Sort direction applied to the attribute specified by sortBy.

```json
{
  "description": "Sort direction applied to the attribute specified by sortBy.",
  "in": "query",
  "name": "sortOrder",
  "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/4",
  "schema": {
    "enum": [
      "ascending",
      "descending"
    ],
    "type": "string"
  }
}
```

### sortBy

Location: query. Required: no.

User attribute to sort by.

```json
{
  "description": "User attribute to sort by.",
  "example": "userName",
  "in": "query",
  "name": "sortBy",
  "pointer": "/paths/~1v2~1scim~12.0~1Users/get/parameters/5",
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Response 200 application/scim+json




Schema:

```json
{
  "examples": [
    {
      "Resources": [
        {
          "active": true,
          "displayName": "jonsnow",
          "emails": [
            {
              "display": "jon.snow@docker.com",
              "primary": true,
              "value": "jon.snow@docker.com"
            }
          ],
          "groups": [
            {
              "display": "nightswatch",
              "value": "nightswatch"
            }
          ],
          "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
          "meta": {
            "created": "2022-05-20T00:54:18Z",
            "lastModified": "2022-05-20T00:54:18Z",
            "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c",
            "resourceType": "User"
          },
          "name": {
            "familyName": "Snow",
            "givenName": "Jon"
          },
          "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
          ],
          "userName": "jon.snow@docker.com"
        }
      ],
      "itemsPerPage": 1,
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ],
      "startIndex": 1,
      "totalResults": 1
    }
  ],
  "properties": {
    "Resources": {
      "items": {
        "$ref": "#/components/schemas/scim_user"
      },
      "type": "array"
    },
    "itemsPerPage": {
      "example": 10,
      "type": "integer"
    },
    "schemas": {
      "example": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ],
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "startIndex": {
      "example": 1,
      "type": "integer"
    },
    "totalResults": {
      "example": 1,
      "type": "integer"
    }
  },
  "type": "object"
}
```




Schema example:
```json
{
  "Resources": [
    {
      "active": true,
      "displayName": "jonsnow",
      "emails": [
        {
          "display": "jon.snow@docker.com",
          "primary": true,
          "value": "jon.snow@docker.com"
        }
      ],
      "groups": [
        {
          "display": "nightswatch",
          "value": "nightswatch"
        }
      ],
      "id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
      "meta": {
        "created": "2022-05-20T00:54:18Z",
        "lastModified": "2022-05-20T00:54:18Z",
        "location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c",
        "resourceType": "User"
      },
      "name": {
        "familyName": "Snow",
        "givenName": "Jon"
      },
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "userName": "jon.snow@docker.com"
    }
  ],
  "itemsPerPage": 1,
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "startIndex": 1,
  "totalResults": 1
}
```


### Response 400 application/scim+json

Bad Request


Schema:

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/scim_error"
    },
    {
      "properties": {
        "scimType": {
          "description": "Some types of errors will return this per the specification.",
          "type": "string"
        },
        "status": {
          "example": "400"
        }
      }
    }
  ]
}
```




error:
```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400"
}
```


### Response 401 application/scim+json

Unauthorized


Schema:

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/scim_error"
    },
    {
      "properties": {
        "status": {
          "example": "401"
        }
      }
    }
  ]
}
```




error:
```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "401"
}
```


### Response 403 application/scim+json

Forbidden


Schema:

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/scim_error"
    },
    {
      "properties": {
        "status": {
          "example": "403"
        }
      }
    }
  ]
}
```




error:
```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "403"
}
```


### Response 404 application/scim+json

Not Found


Schema:

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/scim_error"
    },
    {
      "properties": {
        "status": {
          "example": "404"
        }
      }
    }
  ]
}
```




error:
```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "404"
}
```


### Response 500 application/scim+json

Internal Error


Schema:

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/scim_error"
    },
    {
      "properties": {
        "status": {
          "example": "500"
        }
      }
    }
  ]
}
```




error:
```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "500"
}
```


## Complete operation contract

```json
{
  "description": "Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results.\n\n**Sorting:**\n\nSorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters.\n\nThe `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are \"ascending\" and \"descending\".\n\n**Filtering:**\n\nYou can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.\n\nSupported operators are listed below.\n\n- `eq` equal\n- `ne` not equal\n- `co` contains\n- `sw` starts with\n- `and` Logical \"and\"\n- `or` Logical \"or\"\n- `not` \"Not\" function\n- `()` Precedence grouping\n",
  "operationId": "getV2Scim20Users",
  "parameters": [
    {
      "description": "One-based index of the first result to return.",
      "example": 1,
      "in": "query",
      "name": "startIndex",
      "schema": {
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "description": "Maximum number of results to return.",
      "example": 10,
      "in": "query",
      "name": "count",
      "schema": {
        "maximum": 200,
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "description": "SCIM filter expression used to select users.",
      "example": "userName eq \"jon.snow@docker.com\"",
      "in": "query",
      "name": "filter",
      "schema": {
        "type": "string"
      }
    },
    {
      "$ref": "#/components/parameters/scim_attributes"
    },
    {
      "description": "Sort direction applied to the attribute specified by sortBy.",
      "in": "query",
      "name": "sortOrder",
      "schema": {
        "enum": [
          "ascending",
          "descending"
        ],
        "type": "string"
      }
    },
    {
      "description": "User attribute to sort by.",
      "example": "userName",
      "in": "query",
      "name": "sortBy",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "$ref": "#/components/responses/scim_get_users_resp"
    },
    "400": {
      "$ref": "#/components/responses/scim_bad_request"
    },
    "401": {
      "$ref": "#/components/responses/scim_unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/scim_forbidden"
    },
    "404": {
      "$ref": "#/components/responses/scim_not_found"
    },
    "500": {
      "$ref": "#/components/responses/scim_error"
    }
  },
  "security": [
    {
      "scimToken": []
    }
  ],
  "summary": "List users",
  "tags": [
    "scim"
  ]
}
```

## Referenced schemas

- `#/components/parameters/scim_attributes`

- `#/components/responses/scim_bad_request`

- `#/components/responses/scim_error`

- `#/components/responses/scim_forbidden`

- `#/components/responses/scim_get_users_resp`

- `#/components/responses/scim_not_found`

- `#/components/responses/scim_unauthorized`