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

# Invite users to account

## Introduction

Inviting users to an account is a common operation in collaborative workflows. This guide demonstrates how to automate the process of inviting multiple users to an account by specifying their email addresses, roles, and associated workspaces. By following these examples, you can streamline the user onboarding process and integrate it into your existing workflows.

Each example in this guide begins with obtaining an authorization token from the Mudstack API and setting the required headers (`Authorization`, `x-workspace-id`, and `x-account-id`) for every request. These steps ensure secure and properly scoped API interactions.

Authentication is a critical step in interacting with the Mudstack API. Each request requires an authorization token, which is obtained using your API key and secret. Additionally, the `x-workspace-id` and `x-account-id` headers must be included in every request to ensure proper scoping.

This example is particularly useful for scenarios such as:

* Onboarding new team members to an account.
* Assigning roles and workspace access during the invitation process.
* Automating user invitations for large teams.

This example demonstrates how to:

1. Authenticate and retrieve an authorization token.
2. Invite multiple users to an account using the [`/accounts/invites`](../../accounts/invites) endpoint.

## Steps

### Step 1: Authenticate and Retrieve an Authorization Token

Use the [`/auth/token`](../auth/authenticate-api-key) endpoint to retrieve an authorization token. Replace `<your_account_id>`, `<your_key>`, and `<your_secret>` with your account ID, API key, and secret, respectively.

<CodeGroup>
  ```python auth.py theme={null}
  # Python example to retrieve an authorization token
  import requests

  url = "https://api.mudstack.com/auth/token"
  headers = {
      "x-account-id": "<your_account_id>",
      "Content-Type": "application/json"
  }
  data = {
      "key": "<your_key>",
      "secret": "<your_secret>"
  }
  response = requests.post(url, headers=headers, json=data)
  token = response.json()["token"]
  print(token)
  ```

  ```javascript auth.js theme={null}
  // JavaScript example to retrieve an authorization token
  const fetch = require('node-fetch');

  const url = "https://api.mudstack.com/auth/token";
  const headers = {
      "x-account-id": "<your_account_id>",
      "Content-Type": "application/json"
  };
  const data = {
      key: "<your_key>",
      secret: "<your_secret>"
  };

  fetch(url, { method: "POST", headers, body: JSON.stringify(data) })
      .then(res => res.json())
      .then(data => console.log(data.token));
  ```

  ```csharp auth.cs theme={null}
  // C# example to retrieve an authorization token
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program {
      static async Task Main(string[] args) {
          var client = new HttpClient();
          var requestBody = "{\"key\": \"<your_key>\", \"secret\": \"<your_secret>\"}";
          var content = new StringContent(requestBody, Encoding.UTF8, "application/json");
          content.Headers.Add("x-account-id", "<your_account_id>");
          var response = await client.PostAsync("https://api.mudstack.com/auth/token", content);
          var token = await response.Content.ReadAsStringAsync();
          Console.WriteLine(token);
      }
  }
  ```
</CodeGroup>

**Response Example:**

```json theme={null}
{
  "token": "your_generated_token"
}
```

### Step 2: Invite Users to an Account

Use the [`/accounts/invites`](../accounts/invites) endpoint to invite users to an account. Replace `<your_token>`, `<workspace_id>`, and `<account_id>` with your authorization token, workspace ID, and account ID, respectively. Provide the list of users to invite, including their email addresses, roles, and associated workspaces.

<CodeGroup>
  ```python invite-users.py theme={null}
  # Python example to invite users
  import requests

  # Step 1: Authenticate
  auth_url = "https://api.mudstack.com/auth/token"
  auth_data = {
      "key": "<your_key>",
      "secret": "<your_secret>"
  }
  auth_headers = {"x-account-id": "<your_account_id>", "Content-Type": "application/json"}
  auth_response = requests.post(auth_url, headers=auth_headers, json=auth_data)
  token = auth_response.json()["token"]

  # Step 2: Invite users
  url = "https://api.mudstack.com/accounts/invites"
  headers = {
      "Authorization": f"Bearer {token}",
      "x-workspace-id": "<workspace_id>",
      "x-account-id": "<account_id>",
      "Content-Type": "application/json"
  }
  data = {
      "invites": [
          {
              "email": "user1@example.com",
              "roles": ["Editor"],
              "workspace_ids": ["workspace1"]
          },
          {
              "email": "user2@example.com",
              "roles": ["Viewer"],
              "workspace_ids": ["workspace2", "workspace3"]
          }
      ]
  }
  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```

  ```javascript invite-users.js theme={null}
  // JavaScript example to invite users
  const fetch = require('node-fetch');

  // Step 1: Authenticate
  const authUrl = "https://api.mudstack.com/auth/token";
  const authData = {
      key: "<your_key>",
      secret: "<your_secret>"
  };
  const authHeaders = { "x-account-id": "<your_account_id>", "Content-Type": "application/json" };

  fetch(authUrl, { method: "POST", headers: authHeaders, body: JSON.stringify(authData) })
      .then(res => res.json())
      .then(authResponse => {
          const token = authResponse.token;

          // Step 2: Invite users
          const url = "https://api.mudstack.com/accounts/invites";
          const headers = {
              "Authorization": `Bearer ${token}`,
              "x-workspace-id": "<workspace_id>",
              "x-account-id": "<account_id>",
              "Content-Type": "application/json"
          };
          const data = {
              invites: [
                  {
                      email: "user1@example.com",
                      roles: ["Editor"],
                      workspace_ids: ["workspace1"]
                  },
                  {
                      email: "user2@example.com",
                      roles: ["Viewer"],
                      workspace_ids: ["workspace2", "workspace3"]
                  }
              ]
          };

          fetch(url, { method: "POST", headers, body: JSON.stringify(data) })
              .then(res => res.json())
              .then(console.log);
      });
  ```

  ```csharp invite-users.cs theme={null}
  // C# example to invite users
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program {
      static async Task Main(string[] args) {
          // Step 1: Authenticate
          var client = new HttpClient();
          var authUrl = "https://api.mudstack.com/auth/token";
          var authJson = "{\"key\": \"<your_key>\", \"secret\": \"<your_secret>\"}";
          var authContent = new StringContent(authJson, Encoding.UTF8, "application/json");
          authContent.Headers.Add("x-account-id", "<your_account_id>");

          var authResponse = await client.PostAsync(authUrl, authContent);
          var authResponseString = await authResponse.Content.ReadAsStringAsync();
          var token = authResponseString; // Extract token from response

          // Step 2: Invite users
          var url = "https://api.mudstack.com/accounts/invites";
          var json = "{\"invites\": [{\"email\": \"user1@example.com\", \"roles\": [\"Editor\"], \"workspace_ids\": [\"workspace1\"]}, {\"email\": \"user2@example.com\", \"roles\": [\"Viewer\"], \"workspace_ids\": [\"workspace2\", \"workspace3\"]}]}";
          var content = new StringContent(json, Encoding.UTF8, "application/json");

          client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);
          client.DefaultRequestHeaders.Add("x-workspace-id", "<workspace_id>");
          client.DefaultRequestHeaders.Add("x-account-id", "<account_id>");

          var response = await client.PostAsync(url, content);
          var responseString = await response.Content.ReadAsStringAsync();
          Console.WriteLine(responseString);
      }
  }
  ```
</CodeGroup>

**Response Example:**

```json theme={null}
{
  "invites": [
    {
      "email": "user1@example.com",
      "status": "sent"
    },
    {
      "email": "user2@example.com",
      "status": "sent"
    }
  ]
}
```

***

## Explore More Examples

Looking for more examples? Check out the following guides to learn about other use cases:

* [Update Status on Assets](../examples/update-status-on-assets)
* [Search Assets](../examples/search-assets)
* [Get Assets with Outstanding Tasks](../examples/get-assets-with-outstanding-tasks)