---
title: "Graphiant REST API"
slug: "graphiant-portal-rest-api"
description: "Explore Graphiant REST API documentation, authentication, and SDKs for seamless integration and management of resources in the Graphiant Portal."
updated: 2026-09-01T06:16:58Z
published: 2026-09-01T06:16:58Z
canonical: "docs.graphiant.com/graphiant-portal-rest-api"
---

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

# Graphiant REST API

## Getting Started

Graphiant REST API documentation is available both within the Graphiant Portal and on the Graphiant Documentation site.

- [**Graphiant API Documentation**](https://docs.graphiant.com/apidocs) – Browse API guides, authentication examples, SDK information, and REST API documentation.
- **Graphiant Portal (Swagger UI)** – Explore endpoints interactively, test API calls, and download the OpenAPI specification.

The Graphiant Portal can be accessed using REST APIs and the portal allows users to perform CRUD (Create, Read, Update, Delete) actions on resources.

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(805).png)

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(807).png)

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(808).png)

Portal REST APIs OpenAPI (Swagger specification) can also be downloaded from v1/docs API response. It can be used to generate REST Client on any preferred language choice.

**Graphiant-SDK-Python**

[GitHub - Graphiant-Inc/graphiant-sdk-python: Python SDK for Graphiant NaaS](https://github.com/Graphiant-Inc/graphiant-sdk-python)

**Graphiant-SDK-Go**

[GitHub - Graphiant-Inc/graphiant-sdk-go: Go SDK for Graphiant NaaS](https://github.com/Graphiant-Inc/graphiant-sdk-go)

**Graphiant-Playbooks**

[GitHub - Graphiant-Inc/graphiant-playbooks: Playbooks for Graphiant NaaS](https://github.com/Graphiant-Inc/graphiant-playbooks)

## **Topology**

![Diagram illustrating Graphiant Portal integration with SDKs and Terraform for automation.](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/Graphiant SDKs & Playbooks(3).png)

## REST API User Authentication

### User Token

Graphiant portal supports token based authentication. In order to retrieve the token, user needs to send request to API v1/auth/login with username and password. Response will contain a token and accountType of the user. accountType can be msp, enterprise or graphiant.

Request URL

```plaintext
https://api.graphiant.com/v1/auth/login
```

Request

```plaintext
curl -X 'POST' \
  'https://api.graphiant.com/v1/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "user_msp_1_test_perf_test_enterprise_1@graphiant.com",
  "password": "xxxxxxxxxxx"
}'
```

Response

```plaintext
{
  "auth": true,
  "accountType": "enterprise",
  "token": "gr-auth-d424b93c-957d-43fc-9b70-a20ab187d84f-e3e648ff-ae96-4c40-9698-0bbd765d44d9"
}
```

### Using Token in Authorization Headers on All Other Subsequent Graphiant APIs for Authentication

Once the token is retrieved from the portal and it can be used in all other further Graphiant portal REST APIs requests’s Authoriziation header when sending requests for authentication.

Request URL

```plaintext
https://api.graphiant.com/v1/enterprises
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/enterprises' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-d424b93c-957d-43fc-9b70-a20ab187d84f-e3e648ff-ae96-4c40-9698-0bbd765d44d9'
```

```plaintext
{
  "enterprises": [
    {
      "enterpriseId": 10000000999,
      "companyName": "msp_1_test_perf_test_enterprise_1",
      "accountType": "enterprise",
      "parentEnterpriseId": 10000000998,
      "parentCompanyName": "msp_1_test_perf",
      "adminEmail": "msp_1_test_perf_test_enterprise_1_admin@graphiant.com"
    }
  ]
}
```

> [!NOTE]
> Note:
> 
> User token can also be fetched from browser developer tools by login to Portal UI and tracking the request’s Authorization header. Portal supports local/saml password login methods.

### User Token Expiry

User token is valid for 30minutes and it will be expired after 30 minutes. Token can be refreshed before it is getting expired.

Sample error response when token used in request is expired one.

```plaintext
{
  "errorCode": 403,
  "displayError": "Token Expired",
  "detailedError": ""
}
```

Other possible error responses can be 'Invalid Token' and 'User logged out'

### User Token Refresh

User token can be refreshed using the existing token (current/expired).

Request URL

```plaintext
https://api.graphiant.com/v1/auth/refresh
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/auth/refresh' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-d424b93c-957d-43fc-9b70-a20ab187d84f-e3e648ff-ae96-4c40-9698-0bbd765d44d9'
```

Response

```plaintext
{
  "auth": true,
  "accountType": "enterprise",
  "token": "gr-auth-8ba71f0b-8a13-4fb3-b103-f4618bf4e3ec-f186d381-eabf-49a8-87c5-25ac5ef6ceea"
}
```

### User Logout

User can invalidate the current token using API v1/auth/logout

Request URL

```plaintext
https://api.graphiant.com/v1/auth/logout
```

Request

```plaintext
curl -X 'POST' \
  'https://api.graphiant.com/v1/auth/logout' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-8ba71f0b-8a13-4fb3-b103-f4618bf4e3ec-f186d381-eabf-49a8-87c5-25ac5ef6ceea' \
  -d ''
```

Response

```plaintext
{}
```

### User Logout Invalidates the Token

Request URL

```plaintext
https://api.graphiant.com/v1/enterprises
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/enterprises' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-8ba71f0b-8a13-4fb3-b103-f4618bf4e3ec-f186d381-eabf-49a8-87c5-25ac5ef6ceea'
```

Response

```plaintext
{
  "errorCode": 403,
  "displayError": "Invalid Token",
  "detailedError": ""
}
```

## Switch Accounts as MSP User

When MSP admin/user requests for token, token is returned along with the accountType mentioned as msp.

Request URL

```plaintext
https://api.graphiant.com/v1/auth/login
```

Request

```plaintext
curl -X 'POST' \
  'https://api.graphiant.com/v1/auth/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'authorization: Bearer gr-auth-f50cbfaf-47ad-45b9-bbff-8c654215d3b9-60de68c2-5520-4fe8-a14f-acf30aa473f9' \
  -d '{
  "username": "msp_user_msp_1_test_perf_test@graphiant.com",
  "password": "xxxxxxxxxxx"
}'
```

Response

```plaintext
{
  "auth": true,
  "accountType": "msp",
  "token": "gr-auth-f1a35342-b097-4219-84b3-8655b5b644bb-9a2c5faa-d0d7-4686-ab4b-1fa5f4a730dd"
}
```

### Retrieving List of MSP Customers

This MSP has three enterprises. “Enteprises”/”Customers”/”Tenants” words can be used interchangeably.

Request URL

```plaintext
https://api.graphiant.com/v1/enterprises
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/enterprises' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-f50cbfaf-47ad-45b9-bbff-8c654215d3b9-60de68c2-5520-4fe8-a14f-acf30aa473f9'
```

Response

```plaintext
{
  "enterprises": [
    {
      "enterpriseId": 10000000338,
      "companyName": "enterprise_pasteur",
      "accountType": "enterprise",
      "parentEnterpriseId": 10000000998,
      "parentCompanyName": "msp_1_test_perf"
    },
    {
      "enterpriseId": 10000000999,
      "companyName": "msp_1_test_perf_test_enterprise_1",
      "accountType": "enterprise",
      "parentEnterpriseId": 10000000998,
      "parentCompanyName": "msp_1_test_perf",
      "adminEmail": "msp_1_test_perf_test_enterprise_1_admin@graphiant.com"
    },
    {
      "enterpriseId": 10000001000,
      "companyName": "msp_1_test_perf_test_enterprise_2",
      "accountType": "enterprise",
      "parentEnterpriseId": 10000000998,
      "parentCompanyName": "msp_1_test_perf",
      "adminEmail": "msp_1_test_perf_test_enterprise_2_admin@graphiant.com"
    },
    {
      "enterpriseId": 10000000998,
      "companyName": "msp_1_test_perf",
      "accountType": "msp",
      "parentEnterpriseId": 10000000000,
      "parentCompanyName": "Graphiant Inc",
      "adminEmail": "msp_1_test_perf_test_admin@graphiant.com"
    }
  ]
}
```

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(810).png)

### User Context

An MSP user can impersonate to its tenant enterprises if user is assigned permission to manage those enterprises. Even if is admin MSP user, user needs to be assign explicit association.

MSP user’s context can be identified from v1/auth/user API. This below examples show user is working on the MSP itself(10000000998 is enterpriseId of MSP msp_1_test_perf itself)

Request URL

```plaintext
https://api.graphiant.com/v1/auth/user
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/auth/user' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-f50cbfaf-47ad-45b9-bbff-8c654215d3b9-60de68c2-5520-4fe8-a14f-acf30aa473f9'
```

```plaintext
{
  "userId": "00uoxx12lcKxeuPSG5d7",
  "enterpriseId": 10000000998,
  "permissions": {
    "assetManager": "read_write",
    "networkConfiguration": "read_write",
    "servicePolicies": "read_write",
    "safetyAndSecurity": "read_write",
    "globalServices": "read_write",
    "userAndTenantManagement": "read_write",
    "insights": "read_write",
    "reports": "read_write",
    "monitoringAndTroubleshooting": "read_write",
    "compliance": "read_write",
    "logs": "read_write",
    "developerTools": "read_write",
    "licensing": "read_write",
    "billingAndInvoicing": "read_write",
    "orderStatus": "read_write",
    "support": "read_write",
    "gateway": "read_write",
    "b2b": "read_write"
  },
  "timeZone": ""
}
```

This user has permission to switch to only these two enterprises as the user belong to the group does not have assigned all the enterprises to the user.

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(811).png)

Request

```plaintext
 https://api.graphiant.com/v1/users/00uoxx12lcKxeuPSG5d7/enterprises
```

Response

```plaintext
{
    "enterprises": [
        {
            "enterpriseId": 10000000999,
            "companyName": "msp_1_test_perf_test_enterprise_1",
            "accountType": "enterprise"
        },
        {
            "enterpriseId": 10000001000,
            "companyName": "msp_1_test_perf_test_enterprise_2",
            "accountType": "enterprise"
        }
    ]
}
```

### Switching MSP User Context to One of Its Customers

Using v1/auth/session API, MSP user can switch to one of its customer enterprises.

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(812).png)

Request

```plaintext
https://api.graphiant.com/v1/auth/session?enterpriseId=10000000999
```

Now the context of the user shows 10000000999 enterpriseId

Request

```plaintext
https://api.graphiant.com/v1/auth/user
```

```plaintext
{
    "userId": "00uoxx12lcKxeuPSG5d7",
    "enterpriseId": "10000000999",
    "permissions": {
        "assetManager": "read_write",
        "networkConfiguration": "read_write",
        "servicePolicies": "read_write",
        "safetyAndSecurity": "read_write",
        "globalServices": "read_write",
        "userAndTenantManagement": "read_write",
        "insights": "read_write",
        "reports": "read_write",
        "monitoringAndTroubleshooting": "read_write",
        "compliance": "read_write",
        "logs": "read_write",
        "developerTools": "read_write",
        "licensing": "read_write",
        "billingAndInvoicing": "read_write",
        "orderStatus": "read_write",
        "support": "read_write",
        "gateway": "read_write",
        "b2b": "read_write"
    },
    "timeZone": ""
}
```

Request URL

```plaintext
https://api.graphiant.com/v1/enterprises
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/enterprises' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-4b77b8bc-544e-4809-a742-321d077a6522-1c05e961-cc70-40b9-9330-86337814de15'
```

Response

```plaintext
{
  "enterprises": [
    {
      "enterpriseId": 10000000999,
      "companyName": "msp_1_test_perf_test_enterprise_1",
      "accountType": "enterprise",
      "parentEnterpriseId": 10000000998,
      "parentCompanyName": "msp_1_test_perf",
      "adminEmail": "msp_1_test_perf_test_enterprise_1_admin@graphiant.com"
    }
  ]
}
```

### Switching MSP User Context Back to Its Enterprise (MSP)

Using v1/auth/session/root API, MSP user can switch back to its own enterprise.

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(813).png)

Request URL

```plaintext
https://api.graphiant.com/v1/auth/session/root
```

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/auth/session/root' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-4b77b8bc-544e-4809-a742-321d077a6522-1c05e961-cc70-40b9-9330-86337814de15'
```

Response

```plaintext
{}
```

Now the user context shows that enterpriseId is back to 10000000998

Request

```plaintext
curl -X 'GET' \
  'https://api.graphiant.com/v1/auth/user' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer gr-auth-4b77b8bc-544e-4809-a742-321d077a6522-1c05e961-cc70-40b9-9330-86337814de15'
```

Request URL

```plaintext
https://api.graphiant.com/v1/auth/user
```

Response

```plaintext
{
  "userId": "00uoxx12lcKxeuPSG5d7",
  "enterpriseId": 10000000998,
  "permissions": {
    "assetManager": "read_write",
    "networkConfiguration": "read_write",
    "servicePolicies": "read_write",
    "safetyAndSecurity": "read_write",
    "globalServices": "read_write",
    "userAndTenantManagement": "read_write",
    "insights": "read_write",
    "reports": "read_write",
    "monitoringAndTroubleshooting": "read_write",
    "compliance": "read_write",
    "logs": "read_write",
    "developerTools": "read_write",
    "licensing": "read_write",
    "billingAndInvoicing": "read_write",
    "orderStatus": "read_write",
    "support": "read_write",
    "gateway": "read_write",
    "b2b": "read_write"
  },
  "timeZone": ""
}
```

## Using REST API

### Getting Device Summary

Using GET v1/edges-summary API, a quick info of available devices in an enterprise can be retrieved.

```plaintext
curl 'https://api.graphiant.com/v1/edges-summary?filter%5Brole%5D=UnknownDeviceRole&filter%5Bstatus%5D=active&upgradeSummary=' \
  -H 'authorization: Bearer gr-auth-67f9e847-67a0-45a2-b6f6-fd7a35361d5f-6843463e-3961-4e3f-a9df-2c6bd1d0e9d5'
```

```plaintext
{
    "edgesSummary": [
        {
            "deviceId": 30000051803,
            "enterpriseId": 10000000288,
            "role": "cpe",
            "status": "active",
            "hostname": "edge-1-sdktest",
            "serialNum": "5020cf30-fcee-4f02-93af-8a5ba61f1f0b",
            "model": "QEMU-Q35",
            "site": "San Jose-sdktest",
            "overrideRegion": "us-west-2 (San Jose)",
            "siteId": 4716,
            "lastBootedAt": {
                "seconds": 1750202669,
                "nanos": 537864000
            },
            "portalStatus": "Ready",
            "location": {
                "addressLine1": "",
                "addressLine2": "",
                "city": "tower hamlets",
                "provinceCode": "",
                "state": "greater london",
                "stateCode": "",
                "country": "united kingdom",
                "countryCode": ""
            },
            "region": "eu-west-1 (London)",
            "swVersion": "2506.202506021956",
            "swName": "25.6.1",
            "discoveredLocation": "Tower Hamlets, Greater London, United Kingdom",
            "firstAppearedOn": {
                "seconds": 1750202765,
                "nanos": 314421000
            },
            "ipDetected": "62.89.143.70",
            "isNew": true,
            "ttConnCount": 2
        }
    ],
    "isNewCount": 1
}
```

### Updating Device Configuration

Before updating a device (edge/gateway/core) configuration, it is required to make sure that the device’s Portal Sync status to be in InSync state (a.k.a Ready state). Also it is required to makesure that device has connectivity to Graphiant portal via Graphiant tunnel terminators. These two information can be found from v1/edges/summary API

E.g validate **edge_summary.portalStatus == 'Ready' and edge_summary.ttConnCount == 2** in the API response of interested edge.

#### Sample Device Configuration

**E.g. Request to delete a subinterface**

```plaintext
curl 'https://api.graphiant.com/v1/devices/30000051803/config' \
  -X 'PUT' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'accept-language: en-US,en;q=0.9' \
  -H 'authorization: Bearer gr-auth-0297284c-0179-4df2-ae89-99c9701f7c7c-63838a76-bb73-4a57-9472-70fc000a032a' \
  -H 'content-type: application/json' \
  --data-raw '{"edge":{"interfaces":{"GigabitEthernet8/0/0":{"interface":{"subinterfaces":{"18":{"interface":null}}}}}},"description":"deleting a subinterface ","configurationMetadata":{"name":""}}'
```

```plaintext
{"jobId":1552067}
```

**Eg. Request to a subinterface and configure lan segment**

```plaintext
curl 'https://api.graphiant.com/v1/devices/30000051803/config' \
  -X 'PUT' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'accept-language: en-US,en;q=0.9' \
  -H 'authorization: Bearer gr-auth-0297284c-0179-4df2-ae89-99c9701f7c7c-63838a76-bb73-4a57-9472-70fc000a032a' \
  -H 'content-type: application/json' \
  --data-raw '{"edge":{"interfaces":{"GigabitEthernet8/0/0":{"interface":{"subinterfaces":{"18":{"interface":{"vlan":18,"lan":"lan-7-test","alias":"non_production","description":"lan-7","adminStatus":true,"ipv4":{"address":{"address":"10.2.7.1/24"},"dhcp":{"dhcpClient":false}},"ipv6":{"address":{"address":"2001:10:2:7::1/64"},"dhcp":{"dhcpClient":false}},"isNew":true}}}}}},"segments":{"lan-7-test":{"networks":[],"bgpRedistribution":{},"bgpNeighbors":{},"syslogTargets":{},"staticRoutes":{},"dhcpSubnets":{},"bgpAggregations":{},"ipfixExporters":{}}}},"description":"adding a subinterface","configurationMetadata":{"name":""}}'
```

```plaintext
{"jobId":1552069}
```

The response of the Update device configuration contains jobId. Using jobs API one can find the result of configuration push.

The request payload can also be captured using Browser UI developer tools “Copy as cURL” feature.

![](https://cdn.document360.io/d86ecd1c-49f6-4fac-83cc-5e344f28f84f/Images/Documentation/image(814).png)