Graphiant Portal REST API

  • Published on Jun 19, 2025
  • 8 minute(s) read
  • KD
 Prev Next

Getting Started

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

Graphiant portal hosts developer tools Swagger UI which is generated based on OpenAPI specification (formerly knowns as  Swagger spec) to tryout all the APIs in the portal itself.

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

Graphiant-SDK-Go

GitHub - Graphiant-Inc/graphiant-sdk-go: Go SDK for Graphiant NaaS

Graphiant-Playbooks

GitHub - Graphiant-Inc/graphiant-playbooks: Playbooks for Graphiant NaaS

Topology

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

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

Request

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

{
  "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

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

Request

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'
{
  "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:

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.

{
  "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

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

Request

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

{
  "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

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

Request

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

{}

User logout invalidates the token

Request URL

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

Request

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

{
  "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

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

Request

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

{
  "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

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

Request

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

{
  "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"
    }
  ]
}

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

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

Request

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'
{
  "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.

Request

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

Response

{
    "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.

Request

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

Now the context of the user shows 10000000999 enterpriseId

Request

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

{
    "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

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

Request

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

{
  "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.

Request URL

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

Request

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

{}

Now the user context shows that enterpriseId is back to 10000000998

Request

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

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

Response

{
  "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. 

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' 
{
    "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

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":""}}'
{"jobId":1552067}

Eg. Request to a subinterface and configure lan segment 

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":""}}'
{"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.

Related articles