IoT Accelerator Developer Portal

https://iotdeveloper.aeris.net/hc/en-us/
Admin
The IoT Accelerator Developer Portal provides guidelines, instructions, tutorials, tools, and code...
Tokens:1,901,196
Snippets:5,062
Trust Score:7.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Authentication and API Call Example

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJecU_4fd986_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--c2df99c9502b40aead87d435ecdfac758684f1b7

Demonstrates how to make an API call using a Bearer token and provides an example of fetching the token.

```APIDOC
## Authentication type: Bearer
The API uses OAuth2 and OpenID Connect (OIDC) for authentication and authorization. The Authentication is performed by passing a token in the Authorization header in each request, preceded by the word Bearer and a space.

### Request Example (API Call)
```bash
curl -i -X POST "http://<baseURL>/iot/api/ecm/enterprises"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer <TOKEN_GOES_HERE>"
  -d "{\"parent_id\": \"3.77\",..."
```

### Request Example (Token Fetch)
```bash
curl -X POST "https://<baseURL>/iot/api/auth/token"
  -H "accept: application/vnd.dcp-v1+json"
  -H "Content-Type: application/x-www-form-urlencoded"
  -d "grant_type=password&client_id=&username=&password="
```
```

--------------------------------

### API Call Example with Bearer Token

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBcTC_77c7a8_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--236aebc606145ff4aec1797c30abca5413d11f65

Demonstrates how to make an API call using the obtained Bearer token in the `Authorization` header.

```APIDOC
## Making API Calls with Bearer Token

### Description
Authenticated API requests must include the Bearer token in the `Authorization` header. The token should be preceded by the word `Bearer` and a space.

### Method
POST

### Endpoint
`http://<baseURL>/iot/api/ecm/enterprises`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **parent_id** (string) - Required - The parent ID for the enterprise.
- ... (other fields as required by the specific endpoint)

### Request Example
```curl
curl -i -X POST "http://<baseURL>/iot/api/ecm/enterprises" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN_GOES_HERE>" \
  -d "{\"parent_id\": \"3.77\", ...}"
```

### Response
#### Success Response (200)
- The response body will vary depending on the specific API endpoint called.

#### Response Example
(Example for enterprise creation - actual response may differ)
```json
{
  "id": "enterprise-123",
  "name": "Example Enterprise",
  "parent_id": "3.77"
}
```
```

--------------------------------

### API Call - Enterprise Creation

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJcIM_c4fe9d_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--5264fc0311c0acf81f15e7785336f3ad4b63fd19

Example of an API call to create an enterprise, demonstrating the required Authorization header with a Bearer token.

```APIDOC
## POST /iot/api/ecm/enterprises

### Description
Create a new enterprise within the system. This endpoint requires Bearer token authentication.

### Method
POST

### Endpoint
/iot/api/ecm/enterprises

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **parent_id** (string) - Required - The ID of the parent for the new enterprise.
- ... (other enterprise-specific fields)

### Request Example
```json
{
  "parent_id": "3.77",
  "enterprise_name": "Example Enterprise"
}
```

### Response
#### Success Response (201)
- **enterprise_id** (string) - The ID of the newly created enterprise.
- **status** (string) - The status of the enterprise creation.

#### Response Example
```json
{
  "enterprise_id": "4.123",
  "status": "created"
}
```
```

--------------------------------

### Authentication Type: X-access-token

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBcTC_77c7a8_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--236aebc606145ff4aec1797c30abca5413d11f65

Information on authenticating with X-access-token, including login, token reissue, and an example request.

```APIDOC
## Authentication Type: X-access-token

Authentication is performed by including a token in the `X-Access-Token` header of each request. The token can be obtained via the `/login` or `/login-form` endpoints. The response includes the token's expiration time in milliseconds.

**Key Endpoints:**

| Method | Endpoint        | Description                        |
|--------|-----------------|------------------------------------|
| POST   | /login          | Sign in and authenticate the user  |
| POST   | /login-form     | Sign in and authenticate the user  |
| POST   | /token-reissue  | Returns a new token                |

**Example Authentication Request (cURL):**

```bash
curl -X POST "https://<baseURL>/dcpapi/rest/useradministration/login" \
  -H "accept: application/vnd.dcp-v1+json" \
  -H "Content-Type: application/json" \
  -d "{ \"userId\":\"<USERNAME>\", \"password\":\"<PASSWORD>\"}"
```

Replace `<baseURL>`, `<USERNAME>`, and `<PASSWORD>` with your actual service base URL and credentials.
```

--------------------------------

### Example API Call with Bearer Token

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJedd_0070d3_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCQ%3D%3D--7c42baf56a0c6ce744f6c29d9a75f459d13eea0e

This example demonstrates how to make an API call including the Bearer token in the Authorization header.

```APIDOC
## Example API Call

### Description
An example of an API call to create an enterprise, including the necessary `Authorization` header with a Bearer token.

### Method
POST

### Endpoint
`/iot/api/ecm/enterprises`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **parent_id** (string) - Required - The ID of the parent enterprise.
- ... (other fields as required by the specific endpoint)

### Request Example
```bash
curl -i -X POST "http://<baseURL>/iot/api/ecm/enterprises" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN_GOES_HERE>" \
  -d "{\"parent_id\": \"3.77\", ... }"
```

### Response
#### Success Response (200)
- The response body will vary depending on the specific endpoint called.

#### Response Example
(Example response body not provided in the source text for this specific endpoint)
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-quick-start-guide

Details on how API permissions are managed and how to check for necessary authorizations.

```APIDOC
## API Permissions Overview

### Description
API endpoint permissions are granted by an authorization server based on your account roles. You can verify your permissions in the Service Portal.

### How to Check Permissions
Navigate to **Administration > Users & roles > Permission library** or **Role administration > Actions > View permission library** within the Service Portal to see available permissions for your account.

### Future Documentation
A table summarizing the required permissions for each API endpoint will be available soon.
```

--------------------------------

### General Request Example with Authentication

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776676262167

Example of a GET request including the Authorization header with a Bearer token.

```APIDOC
## GET /iot/api/consumer-connectivity/subscriptions/IMSI/{A_Specific_IMSI}

### Description
Example request demonstrating how to include the Authorization header for an API call.

### Method
GET

### Endpoint
`/iot/api/consumer-connectivity/subscriptions/IMSI/<A_Specific_IMSI>`

### Parameters
#### Path Parameters
- **A_Specific_IMSI** (string) - Required - The IMSI of the subscription to query.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Format: `Bearer <TOKEN_GOES_HERE>`.
- **Accept** (string) - Required - Specifies the desired response format. Example: `application/vnd.dcp-v1+json`.

### Request Example
```bash
curl -i -X GET "http://<baseURL>/iot/api/consumer-connectivity/subscriptions/IMSI/<A_Specific_IMSI>" \
     -H "Accept: application/vnd.dcp-v1+json" \
     -H "Authorization: Bearer <TOKEN_GOES_HERE>"
```
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-quick-start-guide

Information on how API endpoint permissions are authorized and how to check the permissions available for your account.

```APIDOC
## API Permissions

### Description

API endpoint permissions are authorized by an authorization server based on your account roles. You can view the permissions available for your account in the Service Portal.

### Checking Permissions

Navigate to the following menu in the Service Portal:
`Administration > Users & roles > Permission library` or `Role administration > Actions > View permission library`.

Ensure that the necessary permissions are available for your account before utilizing an API. A table summarizing the required permissions for different APIs will be available soon in this section.
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBci4_f4dbdd_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCQ%3D%3D--0c05fffe240e4a1d86cf03d095a72d9832223148

Information on how API permissions are authorized and how to check available permissions for your account.

```APIDOC
## API Permissions

### Description
API endpoint permissions are authorized by an authorization server based on account roles. Ensure you have the necessary permissions before utilizing an API.

### Checking Permissions
You can view available permissions for your account through the permission library in the Service Portal by navigating to:
Administration > Users & roles > Permission library
OR
Role administration > Actions > View permission library

*Note: A table summarizing required permissions for different APIs will be available soon.*
```

--------------------------------

### Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-Quick-start-guide

Explanation of how API endpoint permissions are authorized and where to view available permissions.

```APIDOC
## API Permissions

API endpoints permission are authorized by authorization server based on the account roles. You can view available permissions for your account through permission library in Service Portal by navigating under the following menu: Administration > Users & roles > Permission library or Role administration > Actions > View permission library. Make sure permission is available to your account before you start utilizing this API.
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-Quick-start-guide

Information on how API permissions are managed and how to check for necessary authorizations before using API endpoints.

```APIDOC
## API Permissions

### Description
API endpoint access is controlled by permissions authorized by an authorization server, based on account roles. Users can view their available permissions through the permission library in the Service Portal.

### Accessing Permission Library
Navigate to:
`Administration > Users & roles > Permission library`
OR
`Role administration > Actions > View permission library`

Ensure the required permission is assigned to your account before attempting to use an API endpoint. A table summarizing required permissions for different APIs will be available soon.
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBcTC_77c7a8_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--236aebc606145ff4aec1797c30abca5413d11f65

Information on how API permissions are managed and how users can check their granted permissions.

```APIDOC
## API Permissions

### Description
API endpoint permissions are granted by an authorization server based on account roles. Users can view their permissions in the Service Portal.

### Accessing Permission Information
Navigate to:
Administration > Users & roles > Permission library
OR
Role administration > Actions > View permission library

Users must ensure they have the necessary permissions before utilizing an API. A table summarizing required permissions for different APIs will be available soon.
```

--------------------------------

### Shared Bundle API (Bearer Token)

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-quick-start-guide

APIs such as Shared Bundle, Enterprise Management, eUICC Setup, Device Reconnect, and others utilize Bearer token authentication.

```APIDOC
## Shared Bundle API Authentication

### Description
This API group uses Bearer token authentication. The token is typically obtained via a POST /token endpoint.

### Method
(Various, e.g., GET, POST, PUT, DELETE)

### Endpoint
(Specific endpoints vary by API group)

### Parameters
#### Request Header
- **Authorization** (string) - Required - The authentication token in the format: `Bearer <your_token>`.

### Request Example
```bash
curl -X GET "https://<baseURL>/api/resource"
  -H "Authorization: Bearer your_access_token"
```

### Response
(Response details depend on the specific API endpoint)
```

--------------------------------

### API Rate Limit Exceeded Error Response Body (Example)

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-quick-start-guide

This example shows the JSON response body when an API rate limit has been exceeded. The system returns an error code 429 and a message indicating that the limit has been reached, prompting the client application to reduce its call frequency.

```json
  {"message":"API rate limit exceeded"}
```

--------------------------------

### Authentication - Get Bearer Token

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJcIM_c4fe9d_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--5264fc0311c0acf81f15e7785336f3ad4b63fd19

This endpoint is used to obtain an OAuth2/OIDC Bearer token for authenticating API requests. It requires grant type, client ID, username, and password.

```APIDOC
## POST /iot/api/auth/token

### Description
Obtain an OAuth2/OIDC Bearer token for API authentication.

### Method
POST

### Endpoint
/iot/api/auth/token

### Parameters
#### Query Parameters
None

#### Request Body
- **grant_type** (string) - Required - The grant type for the token request (e.g., 'password').
- **client_id** (string) - Required - The client ID for authentication.
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```json
{
  "grant_type": "password",
  "client_id": "YOUR_CLIENT_ID",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained Bearer token.
- **token_type** (string) - The type of token (e.g., 'Bearer').
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
```json
{
  "access_token": "eyJ...".substring(0, 128),
  "token_type": "Bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJecU_4fd986_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--c2df99c9502b40aead87d435ecdfac758684f1b7

Information on how API endpoint permissions are managed and how to check available permissions for your account.

```APIDOC
## API Permissions

### Description
API endpoint permissions are managed by an authorization server based on account roles. Users can view their available permissions in the Service Portal.

### Accessing Permissions
Navigate to **Administration > Users & roles > Permission library** or **Role administration > Actions > View permission library** in the Service Portal to view your account's permissions.

### Future Updates
A table summarizing the required permissions for different API endpoints will be provided in this section soon.
```

--------------------------------

### Example GET Request for Events

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776687486231-Subscription-Signalling-Events-2-1-3

Demonstrates a basic GET request to retrieve events, including an example of filtering specific fields in the response. The `fields` parameter allows for a subset of data to be returned, reducing payload size.

```http
GET /events/WOh6LIABUqU6IY0JSVLK

GET /events/WOh6LIABUqU6IY0JSVLK?__fields=(imsi,lac)
```

--------------------------------

### SOAP wss-security Authentication Header Example

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887

This snippet demonstrates the structure of the authentication header for SOAP APIs utilizing the Web Services Security (WSS) specification. It includes placeholders for username and password, which are essential for authenticating requests.

```xml
<soapenv:Header>
  <wsse:Security 
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      wsse:mustUnderstand="1">
  <wsse:UsernameToken>
  <wsse:Username>{{My_UserID}}</wsse:Username>
  <wsse:Password>{{My_Password}}</wsse:Password> 
  </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>
```

--------------------------------

### API Rate Limit Headers

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJecU_4fd986_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--c2df99c9502b40aead87d435ecdfac758684f1b7

This section describes the response headers used to track API call limits per second and per minute. It also shows an example of the response body when the rate limit is exceeded.

```APIDOC
## API Rate Limiting

### Description
APIs using BEARER TOKEN Authentication have a maximum number of API calls per second, which is set per application. The system provides rate limit information through response headers.

### Response Headers
- **X-RateLimit-Remaining-second** (integer) - The number of API calls remaining for the current second.
- **X-RateLimit-Limit-second** (integer) - The maximum number of API calls allowed per second.
- **X-RateLimit-Remaining-minute** (integer) - The number of API calls remaining for the current minute.
- **X-RateLimit-Limit-minute** (integer) - The maximum number of API calls allowed per minute.

*Note: Some responses might only contain per-second limits or omit rate limit information entirely during an alignment process.* 

### Error Handling
When the rate limit is reached, API calls will be rejected with an HTTP 429 status code.

#### Response Body Example (429 Too Many Requests)
```json
{
  "message": "API rate limit exceeded"
}
```

### Recommendation
If the rate limit is exceeded, decrease the frequency of API calls to avoid overloading the system.
```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBfWU_eb920d_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCA%3D%3D--b85e5b850d3de00f4100f4057844dd34d7327af7

Details on how API endpoint permissions are authorized and how to check available permissions for your account.

```APIDOC
## API Permissions

API endpoints permission are authorized by authorization server based on the account roles. You can view available permissions for your account through permission library in Service Portal by navigating under the following menu: Administration > Users & roles > Permission library or Role administration > Actions > View permission library. Make sure permission is available to your account before you start utilizing this API.

Soon you will see in this chapter a table which will summarize the permission required to access different API, so that you could use this information when asking your CSP Provider to activate a new API for your role.
```

--------------------------------

### API Rate Limit Exceeded Error Response Body

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-Quick-start-guide

This example shows the typical response body when an API rate limit is exceeded. It returns an HTTP status code 429 (Too Many Requests) and a JSON object with a message indicating the rate limit has been reached.

```json
{"message":"API rate limit exceeded"}
```

--------------------------------

### eUICC Setup API Overview

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776624798231

This section provides an overview of the eUICC Setup API, its purpose, and scope.

```APIDOC
## Introduction

This document describes the IoT Accelerator eUICC Setup API. that provides access and
management of eUICC-related resources such as eUICC Agreements and Localization Tables.
The eUICC Setup API is based on the Representational State Transfer (REST) interface.
From this point on, the eUICC Setup API is referred to as API in this document.

## Scope

This document covers the following topics:

— An overview of the API

— A detailed description of all operations offered by the API
```

--------------------------------

### Token Fetch Example

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776692677015

Example using curl to fetch an authentication token.

```APIDOC
## POST /iot/api/auth/token

### Description
This endpoint is used to fetch an authentication token using OAuth2 grant types.

### Method
POST

### Endpoint
`https://<baseURL>/iot/api/auth/token`

### Headers
- **Accept** (string) - Required - `application/vnd.dcp-v1+json`
- **Content-Type** (string) - Required - `application/x-www-form-urlencoded`

### Request Body
- **grant_type** (string) - Required - The grant type for the OAuth2 flow (e.g., `password`).
- **client_id** (string) - Required - The client ID for your application.
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```curl
curl -X POST "https://<baseURL>/iot/api/auth/token" -H "Accept: application/vnd.dcp-v1+json" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&client_id=<client_id>&username=<username>&password=<password>"
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained access token.
- **token_type** (string) - The type of token (e.g., `Bearer`).
- **expires_in** (integer) - The lifetime in seconds of the access token.

#### Response Example
```json
{
  "access_token": "<YOUR_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### Fetching Bearer Token for Authentication

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-Quick-start-guide

This example shows how to obtain an access token required for Bearer token authentication. It uses a cURL command to send a POST request to the token endpoint with form-urlencoded data, including grant type, client ID, username, and password.

```shell
curl -X POST "https://<baseURL>/iot/api/auth/token" \
  -H "accept: application/vnd.dcp-v1+json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id=&username=&password="
```

--------------------------------

### API Response Headers for Rate Limiting

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-Quick-start-guide

This snippet shows example HTTP response headers that indicate the remaining and limit for API calls per second and per minute. These headers are crucial for applications to manage their API call frequency and avoid exceeding rate limits.

```http
**Response header**  

User-Agent: PostmanRuntime/7.29.2
Postman-Token: 3dbd698c-6b26-4902-ab47-xxxxxxxxx
Host: hostname.dotcom
Accept-Encoding: gzip, deflate
Connection: keep-alive

Content-Type: application/json
Content-Length: 9260
Connection: keep-alive
**X-RateLimit-Remaining-second: 9**
**X-RateLimit-Limit-second: 10**
**X-RateLimit-Remaining-minute: 57**
**X-RateLimit-Limit-minute: 60**
X-Flow-ID: 8d7f9e1e-6c01-4e35-9af9-ea04e22c176e
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=16070400; includeSubDomains
X-Robots-Tag: none
Referrer-Policy: strict-origin
Permissions-Policy: geolocation=(), midi=(), sync-xhr=(self), microphone=(),
camera=(), magnetometer=(), gyroscope=(), fullscreen=(), payment=()


```

--------------------------------

### API Permissions

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBcTC_77c7a8_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpBw%3D%3D--236aebc606145ff4aec1797c30abca5413d11f65

Details on how API endpoint permissions are authorized and how to check available permissions for your account.

```APIDOC
## API Permissions

### Description
API endpoint permissions are authorized by an authorization server based on your account roles. You can view the permissions available for your account to ensure you can access the desired APIs.

### Checking Permissions
Navigate to the Permission library in the Service Portal:
1. Go to `Administration > Users & roles > Permission library`.
2. Alternatively, navigate to `Role administration > Actions > View permission library`.

Ensure that the necessary permission is associated with your account before attempting to use an API. A table summarizing required permissions for different APIs will be available soon.
```

--------------------------------

### Making Authenticated API Call with Bearer Token

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-Quick-start-guide

This example demonstrates how to make a POST request to an Aeris IoT API endpoint using Bearer token authentication. It shows the necessary headers, including the Authorization header with the Bearer token. The input is a JSON payload for the enterprise creation.

```shell
curl -i -X POST "http://<baseURL>/iot/api/ecm/enterprises" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN_GOES_HERE>" \
  -d "{\"parent_id\": \"3.77\",..."
```

--------------------------------

### X-access-token Authentication

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBci4_f4dbdd_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCQ%3D%3D--0c05fffe240e4a1d86cf03d095a72d9832223148

Explanation of how to authenticate using X-access-token for REST APIs, including login and token reissue endpoints.

```APIDOC
## Authentication Type: X-access-token

The API authentication is performed by passing a token in the X-Access-Token header in each request. The token can be acquired using the `/login` or `/login-form` endpoints. The login response contains the token expiration time in milliseconds. For prolonged interaction with the API, a new token can be reissued before the expiration of the current one using the `/token-reissue` endpoint.

### Available Endpoints for X-access-token Authentication

| API             | Description                     |
|-----------------|---------------------------------|
| POST /login     | Sign in and authenticate the user |
| POST /login-form| Sign in and authenticate the user |
| POST /token-reissue | Returns a new token             |

### Example of Authentication

```bash
curl -X POST "https://<baseURL>/dcpapi/rest/useradministration/login"
  -H "accept: application/vnd.dcp-v1+json"
  -H "Content-Type: application/json"
  -d "{ \"userId\":\"<USERNAME>\", \"password\":\"<PASSWORD>\"}"
```
```

--------------------------------

### User Authentication API (X-access-token)

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-quick-start-guide

This API group uses X-access-token for authentication. You can obtain a token using the /login or /login-form endpoints.

```APIDOC
## POST /login

### Description
Sign in and authenticate the user.

### Method
POST

### Endpoint
/login

### Parameters
#### Request Body
- **userId** (string) - Required - The user ID for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```json
{
  "userId": "<USERNAME>",
  "password": "<PASSWORD>"
}
```

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
- **expirationTime** (integer) - The token expiration time in milliseconds.

#### Response Example
```json
{
  "token": "your_auth_token",
  "expirationTime": 1678886400000
}
```

## POST /login-form

### Description
Sign in and authenticate the user.

### Method
POST

### Endpoint
/login-form

### Parameters
#### Request Body
- **userId** (string) - Required - The user ID for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```json
{
  "userId": "<USERNAME>",
  "password": "<PASSWORD>"
}
```

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
- **expirationTime** (integer) - The token expiration time in milliseconds.

#### Response Example
```json
{
  "token": "your_auth_token",
  "expirationTime": 1678886400000
}
```

## POST /token-reissue

### Description
Returns a new token.

### Method
POST

### Endpoint
/token-reissue

### Parameters
#### Request Body
- **currentToken** (string) - Required - The current authentication token.

### Request Example
```json
{
  "currentToken": "your_auth_token"
}
```

### Response
#### Success Response (200)
- **newToken** (string) - A new authentication token.
- **expirationTime** (integer) - The new token expiration time in milliseconds.

#### Response Example
```json
{
  "newToken": "your_new_auth_token",
  "expirationTime": 1678886400000
}
```
```

--------------------------------

### Get Cell Global Identity Information (cURL)

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776660218647

Provides an example using cURL to fetch cell global identity information for a subscription. It includes required query parameters like subscriptionIdType and subscriptionId, and the Authorization header for authentication. The example demonstrates a GET request to the cell-global-identities endpoint.

```curl
curl --request GET \
  --url 'https://iot-api.aeris.com/iot/api/subscriptions/cell-global-identities?subscriptionIdType=IMSI&subscriptionId=' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### Aeris IoT API Response Header for Rate Limiting

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBci4_f4dbdd_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCQ%3D%3D--0c05fffe240e4a1d86cf03d095a72d9832223148

This example shows typical response headers from the Aeris IoT API, focusing on rate limiting information. It includes 'X-RateLimit-Remaining-second', 'X-RateLimit-Limit-second', 'X-RateLimit-Remaining-minute', and 'X-RateLimit-Limit-minute' to indicate current and maximum allowed API calls.

```http
Response Headers 
Content-Type: application/json
Content-Length: 9260
Connection: keep-alive
**X-RateLimit-Remaining-second: 9**
**X-RateLimit-Limit-second: 10**
**X-RateLimit-Remaining-minute: 57**
**X-RateLimit-Limit-minute: 60**
X-Flow-ID: 8d7f9e1e-6c01-4e35-9af9-ea04e22c176e
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=16070400; includeSubDomains
X-Robots-Tag: none
Referrer-Policy: strict-origin  
Permissions-Policy: geolocation=(), midi=(), sync-xhr=(self), microphone=(),
camera=(), magnetometer=(), gyroscope=(), fullscreen=(), payment=()
```

--------------------------------

### API Authentication Methods

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBci4_f4dbdd_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCQ%3D%3D--0c05fffe240e4a1d86cf03d095a72d9832223148

Overview of different authentication mechanisms used by various API groups within the IoT Accelerator Service.

```APIDOC
## API Authentication Overview

The IoT Accelerator Service offers several APIs with distinct authentication mechanisms.

### Authentication Types

*   **wss-security**: Used for the Service Portal API (SOAP). Authentication is handled via a `UsernameToken` in the SOAP header.
*   **X-access-token**: Used for User Administration, Consumer Connectivity, Subscription Management, and Device Localization APIs (REST). Authentication is performed by passing a token in the `X-Access-Token` header, acquired via `/login` or `/login-form` endpoints.
*   **Bearer**: Used for Shared bundle, Enterprise Management, eUICC Setup, Device Reconnect, Subscription Change History, Subscription management - additional functions, Search Subscription Details, Ticketing service, Enterprise Provisioning, Custom fields, Subscription location, Subscription signaling usages, Subscription signaling events, and Devices: eUICC inventory view APIs (REST). Authentication is typically done via a Bearer token, often obtained through a `/token` or `/auth/login` endpoint.
*   **HTTP Basic Auth**: Used for SMS messaging API (REST).

Refer to the specific API group for detailed authentication steps and token acquisition methods.
```

--------------------------------

### Aeris IoT API Error Response for Rate Limit Exceeded

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJfcPkTsDzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBci4_f4dbdd_g3LUFQSS1RdWljay1zdGFydC1ndWlkZQY7CFQ6CXJhbmtpCQ%3D%3D--0c05fffe240e4a1d86cf03d095a72d9832223148

This example illustrates the response body when an Aeris IoT API call exceeds the rate limit. It typically returns an HTTP status code 429 and a JSON message indicating that the rate limit has been exceeded.

```json
{\"message\":\"API rate limit exceeded\"}
```

--------------------------------

### API Rate Limiting

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/17507431668887-API-quick-start-guide

Understand how API rate limits are communicated through response headers and how to handle rate limiting errors.

```APIDOC
## API Rate Limiting and Quotas

### Description

REST APIs using BEARER TOKEN Authentication have a maximum limit on API calls per second and per minute, set per application. The system communicates the current capacity and residual capacity through response headers. When the limit is reached, API calls are rejected with a `429 Too Many Requests` error.

### Rate Limit Headers

Look for the following headers in API responses:

- **X-RateLimit-Remaining-second**: The number of requests remaining for the current second.
- **X-RateLimit-Limit-second**: The maximum number of requests allowed per second.
- **X-RateLimit-Remaining-minute**: The number of requests remaining for the current minute.
- **X-RateLimit-Limit-minute**: The maximum number of requests allowed per minute.

*Note: Some responses might only include per-second limits, and some may not include rate limit information at all due to an ongoing alignment process.* 

### Error Handling (429)

When the rate limit is exceeded, the API response body will contain an error message indicating the issue.

#### Response Body Example (Error 429)

```json
{
  "message": "API rate limit exceeded"
}
```

### Action on Rate Limit Exceeded

If you receive a `429` error, you should decrease the frequency of your API calls to avoid overloading the system.
```

--------------------------------

### HTTP GET Request with Versioning

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776687243287-Device-API-0-0-4

Demonstrates an HTTP GET request specifying the desired API version using the 'Accept-Version' header for content negotiation. This example assumes JSON content negotiation.

```http
GET http://<baseURL>/<service>/<resources>
Accept: application/json
Accept-Version: 1.2.3
```

```http
GET http://<baseURL>/<service>/<resources>
Accept: application/json
Accept-Version: 2.0.0
```

--------------------------------

### Get Operator Networks using cURL

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776674620055-Resource-Inventory-1-0-5

Example of how to retrieve operator networks using cURL. This command sends a GET request to the Aeris IoT API endpoint and includes an authorization token.

```shell
curl --request GET \
  --url https://iot-api.aeris.com/iot/api/operator-networks \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### POST /subscriptions

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJecl0jOEzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCJfcP_6dd1b6_9uYWwtRnVuY3Rpb25zLUFQSS0wLTAtNgY7CFQ6CXJhbmtpCA%3D%3D--922da3d6cee4aed5517c9ebddb6d2a5530444fbb

Creates a new subscription.

```APIDOC
## POST /subscriptions

### Description
Creates a new subscription.

### Method
POST

### Endpoint
/subscriptions

### Parameters
#### Request Body
- **type** (string) - Required - The type of the subscription to create.
- **durationMonths** (integer) - Required - The duration of the subscription in months.
- **userId** (string) - Required - The ID of the user for whom the subscription is created.

### Request Example
```json
{
  "type": "premium",
  "durationMonths": 12,
  "userId": "user-abcde"
}
```

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the newly created subscription.
- **type** (string) - The type of the subscription.
- **status** (string) - The initial status of the subscription.
- **startDate** (string) - The start date of the subscription (ISO 8601 format).
- **endDate** (string) - The end date of the subscription (ISO 8601 format).

#### Response Example
```json
{
  "id": "sub-abcde",
  "type": "premium",
  "status": "active",
  "startDate": "2023-10-27T10:00:00Z",
  "endDate": "2024-10-27T10:00:00Z"
}
```
```

--------------------------------

### Get Organization Traffic Data (HTTP/1.1)

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776625021079-Organization-Signaling-Aggregations-API-1-0-0

Example demonstrating how to retrieve aggregated traffic data statistics using an HTTP/1.1 request. This includes specifying the GET method, the URL with the dimension, and the necessary Authorization header.

```http
GET /iot/api/diagnostic-analytics/signaling-aggregations/traffic-usages/__DIMENSION__ HTTP/1.1
Host: iot-api.aeris.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: application/json
Accept-Version: 0.0.1
```

--------------------------------

### General API Guidelines

Source: https://iotdeveloper.aeris.net/hc/en-us/related/click_data=BAh7CjobZGVzdGluYXRpb25fYXJ0aWNsZV9pZGwrCJe5GEfOEzoYcmVmZXJyZXJfYXJ0aWNsZV9pZGwrCBcK7_6896ac_N1YnNjcmlwdGlvbi1TZWFyY2gtQVBJLTAtMC00BjsIVDoJcmFua2kK--9965a2755f2ff0fb9e279ba20d5d5cacaf88e9ae

General guidelines for interacting with the IoTA API, including compatibility and security.

```APIDOC
## General API Guidelines

### Compatibility

- Be tolerant of unknown fields in payloads; ignore new fields but preserve them if necessary for subsequent PUT requests.
- Handle `x-extensible-enum` parameters by being agnostic or providing default behavior for unknown values.
- Be prepared to handle HTTP status codes not explicitly specified in endpoint definitions.
- Follow redirects when the server returns HTTP status 301 Moved Permanently.

### Security

- All API requests are encrypted using the HTTPS protocol.
- Authentication and Authorization are handled via OAuth2 and OpenID Connect (OIDC).
```

--------------------------------

### Get Triggered Action Detail API Example (OpenAPI)

Source: https://iotdeveloper.aeris.net/hc/en-us/articles/21776676207127

OpenAPI definition snippet for retrieving the details of a specific triggered action by its ID. Includes path parameters, response structure, and an example of the detailed response.

```yaml
paths:
  /triggered-actions/{id}:
    get:
      tags:
        - Actions
      summary: Get Triggered Action Detail
      description: |
        This API returns the details of a action corresponding to the given triggered action Id.
      operationId: getTriggeredActionDetails
      parameters:
        - name: id
          in: path
          description: Specifies the triggered action id to filter the trigger action.
          required: true
          schema:
            type: string
            example: REQ201104955229
      responses:
        '200':
          description: OK
          headers:
            X-Flow-Id:
              $ref: '#/components/headers/X-Flow-Id'
            Content-Type:
              $ref: '#/components/headers/Content-Type'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggeredActionDetailsResponse'
              example:
                id: REQ201106502643
                createdAt: '1665643752014'
                modifiedAt: '1665643754214'
                status: COMPLETED
                rulesetId: 183d01a9d171e
                rulesetName: Rearm network change on EP IF network is A localize1
                rulesetLevel: ENTERPRISE
                rule: NETWORK_CHANGE
                conditionDescription: IF network is { 240 }
                conditionType: networkAgreement
                actions:
                  - action: localization
                    status: COMPLETED
                    createdAt: '1665643752016'
                    modifiedAt: '1665643754211'
                    imsi: '100973000764628'
                    msisdn: '200973000765423'
                    iccid: '99987100973000764628'
                    imei: '123456789012345'
                    network:
                      mcc: '240'
                      mnc: '07'
                    ownerOrganizationId: '3.97'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        default:
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - BearerAuth: []
        - Oauth2_auth:
          - 'triggered-actions.read'
```
Tokens:
Raw