> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Users

> Learn about the /users and /user-tokens endpoints.

Learn about the `/users` and `/user-tokens` endpoints.

## The user object

* User objects represent distinct users that have connected their payroll accounts via Argyle Link.
* You can list all users or retrieve a user by ID that you have saved in your database when one of the Argyle Link [callbacks](/legacy/api-reference/callbacks) was invoked.

### Attributes

* `id` (string (uuid), optional): Unique ID of the user.
* `employers_connected` (array of strings, optional)
* `external_metadata` (JSON, optional)

```json theme={}

{
"id": "0994b847-cc69-4d98-bc99-c5e65e762add",
"created_at": "2019-11-27T15:56:50.583Z",
"employers_connected": [
"employerCo",
"rideCo"
],
"data_providers_connected": [
"payrollCo",
"rideCo"
],
"external_metadata": "User group A"
},
null,
2

```

<RefSubLayout.Divider />

## The user token object

* User tokens are temporary access keys that ensure a user's permissions in Argyle Link are scoped to that specific user's data.
* A new user token should be generated every time you are initializing Argyle Link for an existing user.
* User tokens are [JWT tokens](https://jwt.io/) with a short-lived expiry, and are explained in-depth in our [Returning Users Guide](/legacy/guides/argyle-link/flows/returning-users).

### Attributes

* `access` (string, optional): Value passed when initializing Argyle Link for a returning user.

```json theme={}

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIwZDliNWJmMy05N2ZhLTQ3NTctYTEzNi1iMmEwM2QxNzE0MTQiLCJleHAiOjE2NTMyMzIxNDUsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwianRpIjoiNzFkZjgzMGItOGJjYy00MDgyLTkxYzYtNjEwMTE0Njc3ODRhIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIiwidXNlcl9pZCI6IjAxODA1MTllLTYyMGYtYTQ4MC0wYTZkLTMwN2MwODZjMDc3MyJ9.qC0bQ0wFzVIp3I0a7BxjqrRha2Bexw5PycWIh1WQjTw",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTMyMzIxNDUsImp0aSI6ImY4OWQ1NzkyLTcxZjYtNDM5ZS05NjZiLWVkY2M3ODYxODgwYSIsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIn0.Y1KilybzFeNbGEAjkxhJ-VeTZT9i7iTtRHSwDsnH5Bs"
},
null,
2

```

<RefSubLayout.Divider />

## Create a user

**POST** `/v1/users`

* Create a new user.
* No payload is required for this request.
* This request returns the new user's ID and an associated user token.

<Note>
  When creating a user, you have the option to attach external metadata to that user using the [`external_metadata`](/legacy/api-reference/users#object-external_metadata) object. This object can be used to attach any external information, such as a customer group identifier for grouping users. <br /><br />If the `external_metadata` object is specified in the POST request, the API saves that information, but only returns the `id` and `token` fields. Metadata can also be updated with a [PATCH request](/legacy/api-reference/users#update).
</Note>

### Request body

* `external_metadata` (JSON, optional): Any valid JSON, such as a string or an object.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/users \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/users"
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIwZDliNWJmMy05N2ZhLTQ3NTctYTEzNi1iMmEwM2QxNzE0MTQiLCJleHAiOjE2NTMyMjk2MDAsImlhdCI6MTY1MDYzNzYwMCwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwianRpIjoiNzgyZjhlZDYtMzEwMy00YTZmLTgxOTMtZjdjN2JkMmEwMmVmIiwic3ViIjoiMDE4MDUxYWEtZjdhOS1hMGRiLTJmMzgtNmNmYTMyNWU5ZDY5IiwidXNlcl9pZCI6IjAxODA1MWFhLWY3YTktYTBkYi0yZjM4LTZjZmEzMjVlOWQ2OSJ9.U2i5ZOpHcooydnACMNGr1Ok-SmlCshhqCjKilQiXNkM",
  "id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"
},
null,
2

```

<RefSubLayout.Divider />

## Retrieve a user and their metadata

**GET** `/v1/users/{id}`

Retrieves a user object and any associated `external_metadata` of the specified user.

### Path parameters

* `id` (string (uuid), required): ID of the user object to be retrieved.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request GET \\
    --url https://api.argyle.com/v1/users/{id} \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json'

    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/users/{id}"
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.get(url, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
  "id": "0994b847-cc69-4d98-bc99-c5e65e762add",
  "created_at": "2019-11-27T15:56:50.583Z",
  "employers_connected": [
"rideCo"
  ],
  "data_providers_connected": [
"rideCo"
  ],
  "external_metadata": {
"group_id": "Group A5"
  }
},
null,
2

```

<RefSubLayout.Divider />

## Update a user's metadata

**PATCH** `/v1/users/{id}`

* Update external metadata for an already existing user.
* This request returns the user object with the updated external metadata.

### Path parameters

* `id` (string (uuid), required): ID of the user object, whose metadata should be updated.

### Request body

* `external_metadata` (JSON, optional): Any valid JSON, such as a string or object.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request PATCH \\
    --url https://api.argyle.com/v1/users/{id} \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{"external_metadata": {}}'

    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/users/{id}"
    payload = {"external_metadata": {}}
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.patch(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
  "id": "0994b847-cc69-4d98-bc99-c5e65e762add",
  "created_at": "2019-11-27T15:56:50.583Z",
  "employers_connected": ["rideCo"],
  "data_providers_connected": ["rideCo"],
  "external_metadata": {
"customer group": "lending"
  }
},
null,
2

```

<RefSubLayout.Divider />

## List users

**GET** `/v1/users`

* List all users that are associated with your Link key.
* This request returns an object with a `results` property that contains an array of up to `limit` user objects.

### Query parameters

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request GET \\
    --url https://api.argyle.com/v1/users?limit=2 \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json'

    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/users?limit=2"
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.get(url, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

[
  {
"id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"created_at": "2022-04-22T14:26:40.682Z",
"data_providers_connected": [],
"employers_connected": [],
"external_metadata": {}
  },
  {
"id": "0180519e-620f-a480-0a6d-307c086c0773",
"created_at": "2022-04-22T14:12:55.951Z",
"employers_connected": [
  "employerCo",
  "rideCo"
],
"data_providers_connected": [
  "payrollCo",
  "rideCo"
],
"external_metadata": {"customer group": "lending"}
  }
],
null,
2

```

<RefSubLayout.Divider />

## Delete a user

**DELETE** `/v1/users/{id}`

* Delete a user and all accounts associated with that user. In turn, all other resources—profiles, vehicles, documents, etc.—are deleted as well.
* Use this endpoint to delete all information about a user. If you want to delete a single account of a given user, please refer to [deleting an account](/legacy/api-reference/accounts#delete).
* When the user is successfully deleted, this request responds with a `204` status and an empty response body.

<Note>
  **Caution** — Deleting a user object will also delete all accounts and resources associated with the user.
</Note>

### Path parameters

* `id` (string (uuid), required): ID of the user object to be deleted.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request DELETE \\
    --url https://api.argyle.com/v1/users/{id} \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json'

    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/users/{id}"
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.delete(url, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

"204 status code: No content.",
null,
2

```

<RefSubLayout.Divider />

## Create a user token

**POST** `/v1/user-tokens`

* Argyle utilizes [JWT tokens](https://jwt.io/) as user tokens.
* A new user token should be generated every time you are initializing Argyle Link for an existing user. User tokens are short-lived and will expire.
* To create a user token, send a POST request with the request body containing a JSON object with the following format: `{"user": "<id>"}`.
* This request returns a JSON object as its payload, consisting of an `access` token and `refresh` token. **Only the** `access` **token** is passed as the user token when initializing Argyle Link. Visit our [creating user tokens guide](/legacy/guides/argyle-link/flows/returning-users#creating-a-user-token) for more information.

### Request body

* `user` (string (uuid), required): ID of the user object.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/user-tokens \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data {"user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"}
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/user-tokens"
    payload = {"user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"}
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiIwZDliNWJmMy05N2ZhLTQ3NTctYTEzNi1iMmEwM2QxNzE0MTQiLCJleHAiOjE2NTMyMzIxNDUsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwianRpIjoiNzFkZjgzMGItOGJjYy00MDgyLTkxYzYtNjEwMTE0Njc3ODRhIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIiwidXNlcl9pZCI6IjAxODA1MTllLTYyMGYtYTQ4MC0wYTZkLTMwN2MwODZjMDc3MyJ9.qC0bQ0wFzVIp3I0a7BxjqrRha2Bexw5PycWIh1WQjTw",
"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NTMyMzIxNDUsImp0aSI6ImY4OWQ1NzkyLTcxZjYtNDM5ZS05NjZiLWVkY2M3ODYxODgwYSIsImlhdCI6MTY1MDY0MDE0NSwiaXNzIjoiYXJneWxlLWNvcmUtYXV0aC1wcm9kIiwic3ViIjoiMDE4MDUxOWUtNjIwZi1hNDgwLTBhNmQtMzA3YzA4NmMwNzczIn0.Y1KilybzFeNbGEAjkxhJ-VeTZT9i7iTtRHSwDsnH5Bs"
},
null,
2

```