Skip to main content

Apps and tokens

Requirements to create apps​

To create a new application the developer will need:

  • A Bentley user account that belongs to an organisation with Evo entitlements.
  • Access to the Bentley iTwin Developer Portal.
  • Sufficient permissions to create or modify applications.
  • A secure way to store the credentials that are generated.

About Evo access tokens​

Scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account. An application can request one or more scopes and the access token issued to the application will be limited to the scopes granted. Apps created in the iTwin Developer Portal will include a set of Evo and iTwin scopes.

Available Evo scopes:

  • evo.discovery
  • evo.workspace
  • evo.blocksync
  • evo.file
  • evo.object

When requesting an access token you must include a list of scopes. The values in the list must be separated by spaces (not commas) and should always include evo.discovery and evo.workspace. Add extra scopes as required, for example add evo.object for access to the Geoscience Object API or evo.blocksync for access to the Block Model API.

Getting started​

Choose an application type that suits your needs and follow the corresponding tutorial.

  • Native — an application that runs natively on a desktop or mobile device.
  • Service — a machine-to-machine application requiring no user interaction.
  • SPA — a single-page application where everything runs from a single web page.
  • Web App — a traditional web application.

Native apps​

Create the native app​

Native apps will require you to periodically re-authenticate to renew the token. As a result this type of app may not be suitable for automated scripts. If you need your scripts to run without any user interaction, create a service app instead.

  1. Visit https://developer.bentley.com/ and sign in.

  2. Click your profile in the top-right corner and select My Apps. You may need to agree to Bentley developer terms before proceeding.

  3. Click Register New.

  4. Enter an application name and select the option Native: Auth code + PKCE flow.

  5. Add additional application owners, if required.

  6. Enter one or more redirect URIs (required) and logout redirect URIs (optional). In this example we are adding the redirect URI for the API testing tool Postman. The redirect URI will differ depending upon your development environment.

  7. Click Register.

  8. The next screen displays the unique Client ID of your application. You can edit details of your application, if required. You will receive a confirmation email stating that your new application was successfully registered.

  9. Click the button next to the client ID to copy it and send it to your Seequent representative. They will add the necessary scopes to make your application compatible with Evo.

  10. After the Evo scopes have been added your Seequent representative will let you know that your application is ready to go.

Create a native app token​

from http.server import BaseHTTPRequestHandler, HTTPServer
import webbrowser
from urllib.parse import urlparse
from authlib.common.security import generate_token
from authlib.integrations.requests_client import OAuth2Session

# Enter your client ID and redirect URI here
client_id = ""
redirect_uri = ""

# Define the scope of the token
scope = ["evo.discovery", "evo.workspace", "evo.object", "evo.blocksync"]

def get_access_token(client_id: str,
                    redirect_uri: str,
                    authorisation_url: str,
                    access_token_url: str,
                    scope: str) -> str:
    """
    Retrieves an access token for the specified client.

    Args:
        client_id (str): The client ID.
        redirect_uri (str): The redirect URI.
        authorisation_url (str): The authorization URL.
        access_token_url (str): The access token URL.
        scope (str): The scope of the access token.

    Returns:
        str: The access token.

    """

    port = urlparse(redirect_uri).port

    class OAuthHttpServer(HTTPServer):
        def __init__(self, *args, **kwargs):
            super().__init__(*args, **kwargs)
            self.authorization_code = ""

    class OAuthHttpHandler(BaseHTTPRequestHandler):
        def do_GET(self):
            self.send_response(200)
            self.send_header("Content-Type", "text/html")
            self.end_headers()
            self.wfile.write("Redirecting to the Bentley login\n".encode("UTF-8"))

            client.fetch_token(
                url=access_token_url,
                authorization_response=self.path,
                state=state,
                code_verifier=code_verifier,
                grant_type="authorization_code",
            )

            self.wfile.write(
                """
                <html>
                <body>
                    <h2>Authorization request to Bentley has been completed.</h1>
                    <h3>You may now close this tab or window.</h3>
                </body>
                </html>
                """.encode(
                    "UTF-8"
                )
            )
            self.wfile.write(
                '<script> setTimeout("window.close()", 2500);</script>'.encode("UTF-8")
            )  # Timeout only works if already logged in

    with OAuthHttpServer(("", port), OAuthHttpHandler) as httpd:
        client = OAuth2Session(
            client_id = client_id,
            scope = scope,
            redirect_uri = redirect_uri,
            code_challenge_method = "S256"
        )

        code_verifier = generate_token(48)
        auth_uri, state = client.create_authorization_url(
                                authorisation_url,
                                code_verifier=code_verifier
                            )
        webbrowser.open_new(auth_uri)
        httpd.handle_request()

    return client.token["access_token"]


token = get_access_token(
    client_id = client_id,
    redirect_uri = redirect_uri,
    authorisation_url = 'https://ims.bentley.com/connect/authorize',
    access_token_url = 'https://ims.bentley.com/connect/token',
    scope = scope
)

Service apps​

Create the service app​

Data published to Evo using a service application will be associated with a service identity. If you need data to be directly associated with the user who made the API calls, create a native app that requires a user to sign-in with their own credentials.

  1. Visit https://developer.bentley.com and sign in.

  2. Click your profile in the top-right corner and select My Apps. You may need to agree to Bentley developer terms before proceeding.

  3. Click Register New.

  4. Enter an application name and select the option Service: Client credentials flow.

  5. Add additional application owners, if required.

  6. Click Register.

  7. A pop-up window displays the newly created client ID and client secret for your application.

    Close the window after you have saved a copy of the client secret.

  8. The next screen displays the client ID and an auto-generated client email that is unique for your application. On this screen you can edit details of your application and regenerate the client secret if required. You will receive a confirmation email stating that your new application was successfully registered.

  9. Click the buttons next to the client ID and client email to copy them. Forward the values to your organisation administrator or co-administrator who must include them in the formal request to Seequent to add the service identity to the organisation. Seequent will also add the necessary scopes to make your application compatible with Evo.

  10. After the Evo scopes have been added your Seequent representative will let you know that your application is ready to go.

Add the service identity to your organisation in Bentley IMS​

The service identity associated with the service application is essentially a new user in your organisation but must be manually added to the organisation before being used with Seequent Evo APIs.

Read the Bentley knowledge base article Managing Users to learn how to add the service identity to your organisation. If you encounter any difficulties with this step, read the knowledge base article "This user already exists" for assistance.

Assign the service identity to a workspace in the Evo portal​

The service identity must also be assigned to any Evo workspace that the identity needs to access with the Seequent Evo APIs.

  1. Sign in to the Evo portal.

  2. In the Workspaces tab click to open the appropriate workspace.

  3. Click the Permissions tab.

  4. Click the Enter Email Address dropdown menu and choose the email of the service identity. If you can't find the service identity email in the list, contact your Seequent representative.

  5. Give the service identity the appropriate permission and click Assign User. If the identity will be publishing new data, assign the Editor role, otherwise, assign the Viewer role.

    The service identity can now access the workspace via the APIs.

Create a service identity token​

import requests

# Enter your client ID and client secret here
client_id = ""
client_secret = ""

# Define the scope of the token
scope = "evo.discovery evo.workspace evo.object evo.blocksync"

# Define the token URL
token_url = "https://ims.bentley.com/connect/token"

# Define the parameters for the token request
params = {
    "grant_type": "client_credentials",
    "client_id": client_id,
    "client_secret": client_secret,
    "scope": scope
}

# Make the request
response = requests.post(token_url, data=params)

# Extract the token from the response body
token = response.json()["access_token"]

SPA and Web apps​

These apps are similar to native apps. Follow the steps in the tutorial above but choose SPA: Auth code + PKCE flow or Web app: Authorization code flow when creating the app.

Developer Portal

Guides

API Reference

Cookie policy•Terms of use•Privacy policy
© Seequent, The Bentley Subsurface Company