> 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.smartsim.telecom.li/llms.txt.

> Create and authenticate with application tokens for secure M2M communication, including security best practices, IP restrictions, and token expiration handling.

Application tokens are the recommended way to authenticate with the SmartSIM API for machine-to-machine (M2M) communications.
Unlike user credentials, application tokens don't require storing passwords on your servers or dealing with multi-factor authentication (MFA).

Key benefits:

* Create multiple tokens for different applications or environments
* Give each token a role that limits what it can access
* Restrict tokens to specific IP address ranges
* Set expiration dates for automatic revocation
* Revoke individual tokens at any time without affecting others

Security best practices:

* Give each token the most limited role that fits its integration
* Use IP restrictions when your server has a static IP
* Store tokens in environment variables, never in source code
* Rotate tokens periodically and revoke unused tokens

> **Note**
>
> Application tokens are scoped to the Workspace where they were created.
> Two cross-Workspace operations ([Workspace switching](/developers/api/workspaces/authenticate-workspace) and [cross-Workspace SIM transfers](/developers/api/sim/sim-migration-workspace)) temporarily require [user credentials](/developers/auth/user-credentials), but these APIs are being updated to support application tokens.

## Create an application token

To create an `application_token`, send a POST request to `/api/v2/application_token` with these fields:

* `name` (required): a name that identifies the token, from 2 to 64 characters.
* `roles` (required): an array with exactly one role, which sets what the token can do.
  For the role IDs, see [Assign a role to every new token](/developers/auth/application-tokens-v2-migration#assign-a-role-to-every-new-token).
* `expiry_date` (required): the date and time the token expires, at least one day and at most 10 years in the future.
* `ip_restrictions` (optional): the IPv4 addresses or CIDR ranges the token can connect from.
  Leave it out to allow any address.

### Request

POST [https://smartsim.telecom.li/api/v2/application_token](https://smartsim.telecom.li/api/v2/application_token)

**`Complete`**

```curl Complete
curl -X POST https://smartsim.telecom.li/api/v2/application_token \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "CI pipeline token",
  "roles": [
    {
      "id": 3
    }
  ],
  "expiry_date": "2027-08-21T10:00:00.000Z",
  "ip_restrictions": [
    "192.168.0.1",
    "10.10.1.0/24"
  ]
}'
```

**`Complete`**

```python Complete
import requests

url = "https://smartsim.telecom.li/api/v2/application_token"

payload = {
    "name": "CI pipeline token",
    "roles": [{ "id": 3 }],
    "expiry_date": "2027-08-21T10:00:00.000Z",
    "ip_restrictions": ["192.168.0.1", "10.10.1.0/24"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

**`Complete`**

```javascript Complete
const url = 'https://smartsim.telecom.li/api/v2/application_token';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"CI pipeline token","roles":[{"id":3}],"expiry_date":"2027-08-21T10:00:00.000Z","ip_restrictions":["192.168.0.1","10.10.1.0/24"]}'
};

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

**`Complete`**

```go Complete
package main

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

func main() {

	url := "https://smartsim.telecom.li/api/v2/application_token"

	payload := strings.NewReader("{\n  \"name\": \"CI pipeline token\",\n  \"roles\": [\n    {\n      \"id\": 3\n    }\n  ],\n  \"expiry_date\": \"2027-08-21T10:00:00.000Z\",\n  \"ip_restrictions\": [\n    \"192.168.0.1\",\n    \"10.10.1.0/24\"\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))

}
```

**`Complete`**

```ruby Complete
require 'uri'
require 'net/http'

url = URI("https://smartsim.telecom.li/api/v2/application_token")

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  \"name\": \"CI pipeline token\",\n  \"roles\": [\n    {\n      \"id\": 3\n    }\n  ],\n  \"expiry_date\": \"2027-08-21T10:00:00.000Z\",\n  \"ip_restrictions\": [\n    \"192.168.0.1\",\n    \"10.10.1.0/24\"\n  ]\n}"

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

**`Complete`**

```java Complete
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://smartsim.telecom.li/api/v2/application_token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"CI pipeline token\",\n  \"roles\": [\n    {\n      \"id\": 3\n    }\n  ],\n  \"expiry_date\": \"2027-08-21T10:00:00.000Z\",\n  \"ip_restrictions\": [\n    \"192.168.0.1\",\n    \"10.10.1.0/24\"\n  ]\n}")
  .asString();
```

**`Complete`**

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://smartsim.telecom.li/api/v2/application_token', [
  'body' => '{
  "name": "CI pipeline token",
  "roles": [
    {
      "id": 3
    }
  ],
  "expiry_date": "2027-08-21T10:00:00.000Z",
  "ip_restrictions": [
    "192.168.0.1",
    "10.10.1.0/24"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

**`Complete`**

```csharp Complete
using RestSharp;

var client = new RestClient("https://smartsim.telecom.li/api/v2/application_token");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"CI pipeline token\",\n  \"roles\": [\n    {\n      \"id\": 3\n    }\n  ],\n  \"expiry_date\": \"2027-08-21T10:00:00.000Z\",\n  \"ip_restrictions\": [\n    \"192.168.0.1\",\n    \"10.10.1.0/24\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Complete`**

```swift Complete
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "CI pipeline token",
  "roles": [["id": 3]],
  "expiry_date": "2027-08-21T10:00:00.000Z",
  "ip_restrictions": ["192.168.0.1", "10.10.1.0/24"]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://smartsim.telecom.li/api/v2/application_token")! 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()
```

The response contains the token in the `token` field.
Store it right away, because you can't retrieve it later.

### Response (201)

```json
{
  "id": 1234,
  "name": "CI pipeline token",
  "status": {
    "id": 1,
    "description": "ACTIVE"
  },
  "roles": [
    {
      "id": 3,
      "name": "Observer"
    }
  ],
  "created_date": "2026-08-21T10:00:00.000Z",
  "ip_restrictions": [
    {
      "id": 41,
      "ip_address": "192.168.0.1/32"
    },
    {
      "id": 42,
      "ip_address": "10.10.1.0/24"
    }
  ],
  "expiry_date": "2027-08-21T10:00:00.000Z",
  "created_by": {
    "id": 10,
    "username": "john.doe@example.com",
    "type": {
      "id": 0,
      "description": "HUMAN"
    },
    "name": "John Doe"
  },
  "token": "em_Kf3xR9vB2pLm7Qk4tZ..."
}
```

Application tokens start with `em_` and are opaque strings.
Treat them as secrets and don't parse them.
To see when a token expires, read `expiry_date` from the create or list response.
Tokens created in the earlier format keep working.

By default, the create endpoint refuses a new token when a Workspace holds 300 active application tokens.
Deleted tokens don't count toward the limit.
If your integration needs more, contact your Telecom Liechtenstein account manager.

> **Warning**
>
> The v1 endpoints for managing application tokens (`/api/v1/application_token`) are deprecated and stop working on June 1, 2027.
> Authenticating with `POST /api/v1/authenticate` isn't affected.
> To move your integration to v2, see [Migrate to the v2 application token API](/developers/auth/application-tokens-v2-migration).

You can revoke the application token at any time.

> **Tip**
>
> You can also create and view application tokens in the Telecom Liechtenstein Portal.

## Assign a role to an application token

Every application token has exactly one role, and the token can only call the operations that role allows.
Roles work the same way for tokens as for users, so a token with the Observer role can read data but can't change it.

* To choose the role, pass its ID in `roles` when you [create a token with the v2 endpoint](/developers/api/application-tokens/create-application-token).
  The Support role can't be assigned to a token.
* To change the role later, send the new role in `roles` to [update the application token](/developers/api/application-tokens/update-application-token).
  The new role applies to `auth_token`s generated after the change, and an existing `auth_token` keeps the old role until it expires.
  The expiry date and IP restrictions can't be changed after you create the token.
* The v1 create endpoint has no role selection, so every token it creates has the Administrator role.

> **Warning**
>
> A token with the Administrator role can do anything in your Workspace.
> If it leaks, an attacker gets the same access, so choose the most limited role that fits the integration.

## Authenticate with an application token

Once you create an application token, use `/api/v1/authenticate` to generate a JWT `auth_token` that authenticates subsequent API calls.

### Request

POST [https://smartsim.telecom.li/api/v1/authenticate](https://smartsim.telecom.li/api/v1/authenticate)

**`Application Token Authentication`**

```curl Application Token Authentication
curl -X POST https://smartsim.telecom.li/api/v1/authenticate \
     -H "Content-Type: application/json" \
     -d '{
  "application_token": "em_Kf3xR9vB2pLm7Qk4tZ..."
}'
```

**`Application Token Authentication`**

```python Application Token Authentication
import requests

url = "https://smartsim.telecom.li/api/v1/authenticate"

payload = { "application_token": "em_Kf3xR9vB2pLm7Qk4tZ..." }
headers = {"Content-Type": "application/json"}

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

print(response.json())
```

**`Application Token Authentication`**

```javascript Application Token Authentication
const url = 'https://smartsim.telecom.li/api/v1/authenticate';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"application_token":"em_Kf3xR9vB2pLm7Qk4tZ..."}'
};

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

**`Application Token Authentication`**

```go Application Token Authentication
package main

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

func main() {

	url := "https://smartsim.telecom.li/api/v1/authenticate"

	payload := strings.NewReader("{\n  \"application_token\": \"em_Kf3xR9vB2pLm7Qk4tZ...\"\n}")

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

	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))

}
```

**`Application Token Authentication`**

```ruby Application Token Authentication
require 'uri'
require 'net/http'

url = URI("https://smartsim.telecom.li/api/v1/authenticate")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"application_token\": \"em_Kf3xR9vB2pLm7Qk4tZ...\"\n}"

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

**`Application Token Authentication`**

```java Application Token Authentication
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://smartsim.telecom.li/api/v1/authenticate")
  .header("Content-Type", "application/json")
  .body("{\n  \"application_token\": \"em_Kf3xR9vB2pLm7Qk4tZ...\"\n}")
  .asString();
```

**`Application Token Authentication`**

```php Application Token Authentication
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://smartsim.telecom.li/api/v1/authenticate', [
  'body' => '{
  "application_token": "em_Kf3xR9vB2pLm7Qk4tZ..."
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

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

**`Application Token Authentication`**

```csharp Application Token Authentication
using RestSharp;

var client = new RestClient("https://smartsim.telecom.li/api/v1/authenticate");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"application_token\": \"em_Kf3xR9vB2pLm7Qk4tZ...\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Application Token Authentication`**

```swift Application Token Authentication
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["application_token": "em_Kf3xR9vB2pLm7Qk4tZ..."] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://smartsim.telecom.li/api/v1/authenticate")! 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()
```

### Response (200)

```json
{
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

> **Info**
>
> The server returns only an `auth_token`.
> The response doesn't include a `refresh_token`.

## Handle token expiration

When an application token expires or is revoked:

* Any `auth_token` generated from it remains valid until its own expiration
* New authentication attempts with the expired application token fail with a `401 Unauthorized` error
* You need to create a new application token and update your application configuration

To avoid service interruptions:

1. Set up monitoring for authentication failures
2. Create a new application token before the current one expires
3. Update your application to use the new token
4. Revoke the old token after the transition is complete