Getting Started

The xControl Expeto API is a HATEOAS (Hypermedia as the Engine of Application State) driven REST API that enables precise management and customization of your xCore network. Through API endpoints and hypermedia links provided in JSON responses, you can dynamically explore resource relationships and perform a variety of operations using resource IDs.

Authentication Methods⚓︎

The Expeto API supports two authentication methods:

1. Cookie-based Authentication

   Leverages your xControl Admin login credentials and requires an active browser session using HAL Explorer.

   Cookie-based authentication allows you to access the Expeto API using your xControl Admin login credentials through HAL Explorer. This method requires an active administrator session in xControl and cookies enabled in your browser.

   Info

   For more information on how to use HAL Explorer, see Exploring APIs with HAL.

2. API Key (Token) Authentication: Uses an API token for secure access, typically from your terminal or your applications.

   API access token authentication enables secure interaction with the Expeto API, either through a browser-based HATEOAS application or the command line. The access token must be included in the X-API-KEY header for each API request.

   Key Details:

   • Roles: Both Admin and Customer_Admin roles can use API tokens to access the API. However:
     • Only Admin accounts with the Add API Token feature enabled can generate and manage tokens.
     • Customer_Admin accounts can use tokens but cannot create or manage them.
   • Token Scope: The scope of your API token determines which endpoints and methods you can access.
   • Multiple Tokens: A single account can have multiple valid API tokens simultaneously.

   • View Endpoints: Make a GET request to the API Base URL to see available endpoints for your role:

     api.example.com/v1/

   Important

   • All API requests must be made over HTTPS to ensure secure communication.
   • The Add API Token feature must be explicitly enabled by Expeto Support for an admin account to generate tokens. If enabled, the API Tokens section will be visible on the account page in xControl.

Generating an API Token⚓︎

The API token can be generated from xControl and through an API endpoint. Only users with 'Admin' privilege can generate the API token; it is not accessible to Customer_Admin accounts.

From xControl⚓︎

As an Admin account user with the Add API Token feature enabled, you can:

• Generate API tokens for your account or other accounts.
• Delete API tokens for your account.
• Generate API tokens for accounts within the same Customer or Child Customers.

To generate a token for your Admin account from xControl:

1. Open xControl and navigate to your account page.
2. Locate the API Tokens section (only visible if the feature is enabled for your account).
3. Click Add, then provide a name for the token and click Save.
4. A panel will display the API token string and a warning that this is the only time the full token will be shown.
5. Copy the token and save it securely (e.g., in a password manager or text editor).
6. Close the panel.

The new token will appear in the API Tokens section, but its value will be obfuscated, showing only the last four characters for identification.

Using API⚓︎

To generate a token for your Admin account using an API endpoint:

1. Open your API client.

2. Make a POST request to the following endpoint, providing your existing API token in the request header:

   /v1/accounts/command/createToken

Example cURL Request:⚓︎

    curl --request POST \
        --url https://api.example.com/v1/accounts/command/createToken \
        --header 'Content-Type: application/json' \
        --header 'X-API-KEY: <apiKey>' \
        --data '{
        "name": "exampleToken",
        "account": "123456"
        }'

Request Parameters:⚓︎

Once the request is successfully processed, the API will return the new token. Be sure to copy and securely store the token, as it will not be displayed again.

Using the API Token⚓︎

API tokens are available to both Admin and Customer_Admin roles and are required for secure access to API endpoints. Tokens are included in the request header using the X-API-KEY key.

Include the API token in the X-API-KEY header when making API requests via CLI. For example:

    curl --request GET \
      --url https://api.example.com/v1/subs \
      --header 'X-API-KEY: <APIkeyValue>'

Token Expiration⚓︎

If the API token is nearing expiration (within the next 30 days), the API server includes the following additional header in the response:

X-API-KEY-EXPIRING=true

Refreshing the Token⚓︎

To refresh an API token, send a POST request to the following endpoint:

/v1/api-tokens/command/refreshToken

Request Requirements:⚓︎

• The request header must include:
  • Key: X-API-KEY
  • Value: The token that needs to be refreshed.
• Tokens cannot be refreshed if they are less than one hour old.

Example cURL Request:⚓︎

    curl --request POST \
      --url https://api.example.com/v1/api-tokens/command/refreshToken \
      --header 'X-API-KEY: <existingToken>' \
      --header 'Content-Type: application/json'

Response Body:⚓︎

The JSON response contains the following fields:

Status Codes:⚓︎

Deleting the token⚓︎

To delete the API Token:

    curl --request DELETE \
      --url http://localhost/v1/account-feature-api-tokens/{id} \
      --header 'X-API-KEY: <apiKey>'

Making an API Request⚓︎

API calls are sent over HTTPS to Expeto's API server endpoints to access and interact with resources. Each request triggers a response from the API server, containing the requested data or the result of an operation. The main components of an API request include:

Components of an API Request⚓︎

Example Request with cURL⚓︎

By default, a cURL request uses the GET method unless another method is explicitly specified. Below is an example of a GET request with an API token:

    curl --request GET \
      --url https://api.example.com/v1/accounts \
      --header 'X-API-KEY: <APIkey>'

API Request Methods⚓︎

Expeto's REST API supports the following HTTP methods to interact with resources:

The POST, PUT, and PATCH methods require a Content-Type header with a value of application/json and a JSON-formatted body containing the key-value pairs to be created or updated.

A POST or PATCH request can update an existing resource without including all attributes. However, a PUT request requires all attributes to be specified, and any omitted attributes will be set to null.

Base URL and Resource Path⚓︎

The Base URL for the Expeto API is:

https://api.example.com/

An API version number always follows the Base URL. For example:

https://api.example.com/v1

To complete the URL, append the endpoint name corresponding to the desired resource. For example, to access the accounts resource:

https://api.example.com/v1/accounts

Query Parameters⚓︎

When retrieving resources, query parameters allow you to filter, sort, and customize the response. For example, a GET request for all subscribers may return thousands of results. Query parameters such as page, size, sort, and projection help refine how the response is displayed.

Common Query Parameters⚓︎

Example Requests⚓︎

URI Template⚓︎

The following URI template includes placeholders for query parameters:

https://api.expeto.io/v1/subs{?page,size,sort,projection}

Sample Request⚓︎

A GET request to retrieve subscribers on page 23, with 10 results per page, sorted by imsi in descending order:

https://api.example.com/v1/subs?page=23&size=10&sort=imsi,desc

If no projection parameter is specified, the response defaults to detail.

Example JSON Responses⚓︎

Pagination Metadata⚓︎

The page object in the response body provides details about pagination:

    {
      "page": {
        "size": 10,
        "totalElements": 64752,
        "totalPages": 6476,
        "number": 23
      }
    }

Subscriber Example⚓︎

A single subscriber resource in the detail projection might appear as:

    {
      "imsi": "123480002339875",
      "msisdn": "+123480002339875",
      "k": "###MASKED###",
      "opc": null,
      "iccid": "89618802340002598755",
      "status": "Inactive",
      "type": "Production",
      "extensions": {
          "batch": "2022-04-12"
      }
    }

Subscriber with deep Projection⚓︎

A deep projection includes additional details such as system profile settings:

{
  "systemProfile": {
    "_links": {
      "self": {
        "href": "https://api.expeto.io/v1/system-profiles/123456789{?projection}",
        "templated": true
      }
    },
    "name": "internet-209715200-104857600"
  }
}

API Error Responses⚓︎

The Expeto API server returns responses in JSON format, accompanied by HTTP status codes to indicate the outcome of each request:

HTTP Status Codes⚓︎

Successful Response⚓︎

A successful 200 OK response contains the resource's key-value attributes, as defined by the Expeto API schema. For example:

    {
      "version": -89287109,
      "deleted": -16312438,
      "tac": "35607009",
      "brandName": "SAMSUNG",
      "modelName": "SM-G5323G/DS",
      "deviceType": "Smartphone",
      "os": "Android 6.0 Marshmallow",
      "source": "manual",
      "recordTimestamp": "2012-03-28T16:19:27.128Z",
      "id": "Grob's Phone",
      "_links": {}
    }

Error Responses⚓︎

If an error occurs, the API server returns a JSON response with additional information about the issue. For example, if you lack permissions to access a resource, a 403 AccessDenied error is returned:

    {
      "status": 403,
      "error": "AccessDenied",
      "message": "The Security Framework denied access for this request. You are probably not allowed to access this resource.",
      "path": "/v1/notifications",
      "timestamp": 1626387747246,
      "incident": "40530304"
    }

Additional Resources⚓︎

For more information on error codes and troubleshooting, see Troubleshooting API.