> This page is for Developers.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.iot.telia.lt/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.iot.telia.lt/_mcp/server.

# Invite a user

POST https://iot.telia.lt/api/v2/user/invitation
Content-Type: application/json

Invite a user to a Workspace by specifying username and the roles that the user will have in the organization.
This user is created and a `User invited` event is sent.
There is no additional action such as an email sent.

The following fields may be provided:
- `username` (String) - Email of the invited user
- `name` (String) - Name of the invited user
- `organisation` (Object) - Defaults to the default Workspace of the requesting user
- `roles` (Array) - Assigns the **Administrator** role by default

If the invited user doesn't exist, a new user is created and the `organisation.id` is their default Workspace.
If the invited user already exists, the user is assigned to the Workspace.
This fails if the Workspace feature isn't enabled on the target organization's tariff plan.


Reference: https://docs.iot.telia.lt/developers/api/password-management-and-activation/user-v-2-invitation

## Authentication

- `Authorization` header (bearer token, required) — An `auth_token` should be provided to authenticate a session. To obtain an `auth_token`, see the [`/api/v1/authenticate` **POST** request](/developers/api/authentication/authenticate).

## Request

### Body (application/json)

This endpoint expects an object.

- `username` (string, required)
- `name` (string, required)
- `organisation` (ApiV2UserInvitationPostRequestBodyContentApplicationJsonSchemaOrganisation, optional)
- `roles` (list of ApiV2UserInvitationPostRequestBodyContentApplicationJsonSchemaRolesItems, optional)

## Response

### 201

User created successfully

- `id` (double, optional)
- `username` (string, optional)
- `name` (string, optional)
- `organisation` (ApiV2UserInvitationPostResponsesContentApplicationJsonSchemaOrganisation, optional)
- `roles` (list of ApiV2UserInvitationPostResponsesContentApplicationJsonSchemaRolesItems, optional)

## Errors

### 400 Bad Request Error

Some of the given parameters have invalid values, detailed description will be given in the response

- `any`

### 403 Forbidden Error

Current logged in user is not permitted to invite users.

- `any`

### 409 Conflict Error

There is already an active user with the same username, so this cannot be taken

- `any`

## Types

### ApiV2UserInvitationPostRequestBodyContentApplicationJsonSchemaOrganisation

- `id` (integer, optional)

### ApiV2UserInvitationPostRequestBodyContentApplicationJsonSchemaRolesItems

- `id` (integer, optional)

### ApiV2UserInvitationPostResponsesContentApplicationJsonSchemaOrganisation

- `id` (double, optional)

### ApiV2UserInvitationPostResponsesContentApplicationJsonSchemaRolesItems

- `id` (double, optional)
- `name` (string, optional)

## Examples

**Request**

```json
{
  "username": "john.funky@company.org",
  "name": "John Funky Jazz",
  "roles": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}
```

**Response**

```json
{
  "id": 207531,
  "username": "john.funky@company.org",
  "name": "John Funky Jazz",
  "organisation": {
    "id": 6797
  },
  "roles": [
    {
      "id": 1,
      "name": "Administrator"
    },
    {
      "id": 2,
      "name": "User"
    }
  ]
}
```

**SDK Code**

```python User Created
import requests

url = "https://iot.telia.lt/api/v2/user/invitation"

payload = {
    "username": "john.funky@company.org",
    "name": "John Funky Jazz",
    "roles": [{ "id": 1 }, { "id": 2 }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript User Created
const url = 'https://iot.telia.lt/api/v2/user/invitation';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"username":"john.funky@company.org","name":"John Funky Jazz","roles":[{"id":1},{"id":2}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go User Created
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://iot.telia.lt/api/v2/user/invitation"

	payload := strings.NewReader("{\n  \"username\": \"john.funky@company.org\",\n  \"name\": \"John Funky Jazz\",\n  \"roles\": [\n    {\n      \"id\": 1\n    },\n    {\n      \"id\": 2\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby User Created
require 'uri'
require 'net/http'

url = URI("https://iot.telia.lt/api/v2/user/invitation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"username\": \"john.funky@company.org\",\n  \"name\": \"John Funky Jazz\",\n  \"roles\": [\n    {\n      \"id\": 1\n    },\n    {\n      \"id\": 2\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java User Created
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://iot.telia.lt/api/v2/user/invitation")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"username\": \"john.funky@company.org\",\n  \"name\": \"John Funky Jazz\",\n  \"roles\": [\n    {\n      \"id\": 1\n    },\n    {\n      \"id\": 2\n    }\n  ]\n}")
  .asString();
```

```php User Created
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://iot.telia.lt/api/v2/user/invitation', [
  'body' => '{
  "username": "john.funky@company.org",
  "name": "John Funky Jazz",
  "roles": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp User Created
using RestSharp;

var client = new RestClient("https://iot.telia.lt/api/v2/user/invitation");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"username\": \"john.funky@company.org\",\n  \"name\": \"John Funky Jazz\",\n  \"roles\": [\n    {\n      \"id\": 1\n    },\n    {\n      \"id\": 2\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift User Created
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "username": "john.funky@company.org",
  "name": "John Funky Jazz",
  "roles": [["id": 1], ["id": 2]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://iot.telia.lt/api/v2/user/invitation")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```