Most endpoints will require you to specify your cloud ‘Region’ (within the request url) and ‘Instance ID’ (within the request headers).

The ‘Region’ refers to the data center where a cloud instance is hosted.

The ‘Instance ID’ is a GUID to identify each cloud instance.

This article describes various methods to obtain your Region and Instance ID.

Using the GET /clouds endpoint

Assuming you are able to authenticate with the OpenGround API to obtain an access token, you can use the GET /clouds endpoint to obtain your Region & Instance ID.

For Machine Login, this endpoint will return a list of the clouds the current Client ID is associated with.

For User Login, this endpoint will return a list of the clouds in which the current user has an account.

This can be performed using the following request:

URL: GET https://api.openground.bentley.com/api/v1.1/identity/clouds

Headers:

Authorization: Bearer access_token

OpenGroundCloud: U3VwZXJCYXRtYW5GYXN0

For example, using Python:

import requests
import json

# You will need to obtain an access_token
# Not shown here for simplification purposes
access_token = ''

url = 'https://api.openground.bentley.com/api/v1.1/identity/clouds'

headers = {
    'Authorization': 'Bearer {}'.format(access_token),
    'OpenGroundCloud': 'U3VwZXJCYXRtYW5GYXN0',
}

get_clouds = requests.get(url, headers=headers)

clouds = get_clouds.json()
print(json.dumps(clouds, indent=4, sort_keys=False))

Example response:

[
    {
        "Id": "00000000-0000-0000-0000-000000000001",
        "Name": "CloudABC",
        "Region": "uksouth",
        "IdleTimeout": 0,
        "AccountType": 0,
        "IsGovCloud": false
    },
    {
        "Id": "00000000-0000-0000-0000-000000000002",
        "Name": "CloudXYZ",
        "Region": "westeurope",
        "IdleTimeout": 0,
        "AccountType": 1,
        "IsGovCloud": false
    }
]

Within the response, the ‘Id’ is the Instance ID and the ‘Region’ is the Region you would need to use.

Postman

It is possible to access the GET /clouds endpoint from within our Postman Collections. Please also see our Postman Quickstart guide for more information on using our Postman examples.

Contact Support

Alternatively, you can contact support, and we can provide you with your cloud Instance ID and Region.

Using your Region & Instance ID

Most endpoint url’s will need to be updated to include your cloud Region.

For example, the endpoint below can be used to retrieve a list of projects within a cloud:

GET https://api.{{REGION}}.openground.bentley.com/api/v1.0/data/projects

If your region is ‘eastus’, you would need to use the url:

GET https://api.eastus.openground.bentley.com/api/v1.0/data/projects

InstanceID would need to be included as a header in this request.

For example, using Python:

import requests
import json

# Update these values with your specific parameters
INSTANCE_ID = ''
REGION = ''

# You will need to obtain an access_token
# Not shown here for simplification purposes
access_token = ''

url = 'https://api.' + REGION + '.openground.bentley.com/api/v1.0/data/projects'

headers = {
    'OpenGroundCloud': 'U3VwZXJCYXRtYW5GYXN0',
    'User-Agent': 'Python',
    'Authorization': 'Bearer {}'.format(access_token),
    'InstanceID': INSTANCE_ID
}

get_projects = requests.get(url, headers=headers)

projects = get_projects.json()
print(json.dumps(projects, indent=4, sort_keys=False))

Example response:

[
    {
        "Id": "00000000-0000-0000-0000-000000000001",        
        "Group": null,
        "DataFields": [
            {
                "Header": "ProjectID",
                "Value": "Project ABC"
            },
            {
                "Header": "uui_ConfigPack",
                "Value": "00000000-0000-0000-0000-00000000000a"
            }
        ],
        "HasDocuments": null
    },
    {
        "Id": "00000000-0000-0000-0000-000000000002",
        "Group": null,
        "DataFields": [
            {
                "Header": "ProjectID",
                "Value": "Project XYZ"
            },
            {
                "Header": "uui_ConfigPack",
                "Value": "00000000-0000-0000-0000-00000000000b"
            }
        ],
        "HasDocuments": null
    }
]