The OpenGround API uses OAuth 2.0 authentication/authorization. We support both Client Credentials (Machine) and Authorization Code with PKCE (User Login) authentication.
The authentication process will create an access token that can be used to make subsequent API calls.
Access tokens expire after 1 hour. Refresh tokens can be used with User Login authentication to obtain a new access token without user interaction. Refresh tokens expire after 7 days.
You will need a Client ID, and potentially a Client Secret, depending on the authentication method you will be using. For more information, please see this article on how to Request a Client ID & Secret.
User Login authentication can be used when you’d like a user to interactively login to their OpenGround account. This method allows users to access cloud instances and projects granted to their account, based on their assigned roles.
This method is well-suited if you’d like users within your app to inherit their level of access from their OpenGround account. For example, this would be appropriate if you want to create dashboards that only expose data for projects where the user has access, or if you want to integrate a field data collection app and only allow users to upload data to projects where they have access.
As with any other login to OpenGround, this process involves the user logging into their Bentley Identity Management Service (IMS) account to gain access to OpenGround.
For an example of how these parameters are used, please see the Python authentication examples.
To authenticate with Bentley IMS, use the following URL & parameters:
Authorization URL: https://imsoidc.bentley.com/connect/authorize?
client_id: openground-cloud-connector (see here for more info)
client_secret: (blank – see here for more info)
code_challenge: (random, dynamically-generated string)
code_challenge_method: S256
redirect_uri: https://callback.openground.cloud/callback.html or http://localhost:8080 (see below for more info)
response_type: code
scope: openground openid profile email offline_access (note the offline_access scope is optional and is used to obtain a refresh token)
To exchange the authorization code for an access token, use the following endpoint:
Access Token URL: POST https://imsoidc.bentley.com/connect/token
Body:
client_id: openground-cloud-connector (see here for more info)
code: (retrieved from authorization callback)
code_verifier: (hashed version of code_challenge)
grant_type: authorization_code
redirect_uri: https://callback.openground.cloud/callback.html
As noted above the 'offline_access' scope can be used to obtain a refresh token.
A refresh token can be used to obtain a new access token without user involvement.
This can be performed by making the following request:
Access Token URL: POST https://imsoidc.bentley.com/connect/token
Body:
grant type: refresh_token
refresh token: (refresh token obtained during initial authorization flow)
The request can be made after receiving a 401 response. If the request for a new access token also returns a 401 response, the refresh token will have also expired.
The following Redirect URI's can be used by default:
Machine Login can be used for automated, non-interactive authentication workflows. For example, this would be appropriate if you wanted to integrate data from OpenGround into a web GIS or other enterprise platform and did not want to restrict access based on end-user OpenGround account permissions.
For Machine Login, you will need to create a ‘service account’ user within your cloud with the appropriate access levels assigned. For example, if you wanted your application to have full access to all projects and system capabilities, you would assign the service account as a System Admin. We can then generate client credentials (Client ID & Secret) on your behalf that are linked to the service account. For more information, please see this article on how to Request a Client ID & Secret.
For an example of how these parameters are used, please see the Python authentication examples.
To obtain an access token, use the following endpoint:
Access Token URL: POST https://imsoidc.bentley.com/connect/token
Body:
client_id: (see here for more info)
client_secret: (see here for more info)
grant_type: client_credentials
scope: openground