Apps & tokens

Overview

Seequent Evo integrations need a user's consent to access data using Seequent APIs and SDKs. Evo uses OAuth 2.0 to grant access, and an app registered with the iTwin Platform provides the means to initiate the OAuth process.

Before you can create an access token you must first register your app. During registration you must provide basic information such as the app name and redirect URI, which redirects users to the appropriate web server, browser, or native app.

Requirements

To register an app you must have:

• A Bentley user account that belongs to an organisation with Evo entitlements.
• Access to the Bentley iTwin Developer Portal.
• Sufficient permissions to register or modify applications, eg. the developer role at a minimum.
• A method to securely store the app credentials that are generated.

If you access the My Apps page and see the image below, you do not have sufficient permissions to register apps.

Contact your administrator to request access.

About Evo access tokens

Access tokens are digital keys used to verify an authenticate a user's identity before granting access to resources. Access tokens are essential for secure authentication and authorisation processes, ensuring that only authorised users can access specific data or functionalities.

The Evo Python SDK handles the creation and management of access tokens on your behalf and automatically includes the necessary scopes.

Access tokens are valid for 1 hour after creation.

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 registered in the iTwin Developer Portal will include a set of Evo and iTwin scopes.

When requesting an access token you must include a list of scopes. Consult the list below to determine which scopes you need to include.

Recommended Evo scopes

You should always include these scopes in your OAuth requests because they provide access to critical Evo APIs.

• evo.discovery to access the Evo Discovery API.
• evo.workspace to access the Workspaces API.

Optional Evo scopes

Include these scopes to your OAuth requests if you intend to work with the corresponding Evo API.

• evo.blocksync to access the Block Model API.
• evo.file to access the File API.
• evo.object to access the Geoscience Object API.

Optional additional scopes

OAuth apps can refresh a user's access token without requiring the user to sign-in again. This functionality is only available when you include the offline_access scope in your OAuth request. This feature is not available (or required) when using a machine-driven or service app.

The offline_access scope doesn't appear in the list of scopes that you see when you register an app.

Secure storage of app credentials and tokens

Before registering a new app, we highly recommend that you have a secure way to store your app credentials. Securing storing your credentials is important because the app is the door by which your valuable data is accessed. App credentials, and the access tokens that the app creates, should be treated just like any other password.

Hints for securely storing app credentials

• Don't share app credentials with colleagues over email or internal messaging systems. Instead, credentials should be stored in a secure password manager.
• The credentials of a service identity (from a service or machine-driven app) are particularly sensitive, since a bad actor who obtained those credentials could easily access any Evo data available to the service identity.

Hints for securely storing access tokens

• Access tokens should never be committed to source control, eg. to a GitHub repository. Take advantage of pre-commit hooks and other security tools to prevent the accident leakage of access tokens.
• Always save access tokens to a .env file in your project folder or to your system environment directly instead of hard-coding tokens into your source files.
• Never expose access tokens in error messages or log files.

App types

Choose an app that best suits your development requirements.

• User-driven apps require a real person to sign-in. Since the access token represents this person, any interactions with Evo will be attributed to them.

  The iTwin Platform supports these app types for user-driven authentication:

  • Native — an application that runs natively on a desktop or mobile device.
  • SPA — a single-page application where everything runs from a single web page.
  • Web App — a traditional web application.

• Machine-driven authentication does not require a real person to sign-in. Instead, a service identity is created which has it's own unique profile and email address. The service identity must be added to your organisation and to your Evo workspaces just like a regular user.

  The iTwin Platform supports the following app type for machine-driven authentication:

  • Service — a machine-to-machine application requiring no user interaction.

User-driven app

Register the app

User-driven apps require the user to periodically re-authenticate to renew the access token, so this type of app may not be suitable for machine-driven scripts. If you need your scripts to run without any user interaction, register a machine-driven 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 the dropdown arrow on the Register New button and choose Register new app for Seequent Evo.

   

4. Enter an application name and select one of the options: Native/SPA/Web App.

   

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, eg. enter http://localhost:3000/signin-callback for running your app locally.

   

7. Click Register.

   

8. The next screen displays the unique Client ID of your application. Be sure to save the client ID in a secure place. You will receive a confirmation email stating that your new application was successfully registered.

   

Machine-driven app

Register the 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, register a user-driven app that requires a user to sign-in with their own credentials.

For compliance reasons the organisation administrator or co-administrator needs to approve the addition of a service identity to the organisation. Your Seequent representative will include the designated administrator or co-administrator in the formal request email that is sent to the Bentley support team.

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 the dropdown arrow on the Register New button and choose Register new app for Seequent Evo.

   

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.

   You won't be shown the client secret again, so you must save it securely before closing the window!

   

   Important

   DO NOT share the these credentials with Seequent or any other 3rd-party. These values must be kept private.

   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. Be sure to save these credentials in a secure place.

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 box and paste the email of the service identity. Give the service identity the appropriate user role and click Assign user. If the identity will be publishing new data, assign the Editor role, otherwise, assign the Viewer role.

   

Creating and managing access tokens with Python

Seequent actively maintains open-source projects on GitHub that make it easy to build an Evo integration using Python.

Visit Evo Python SDK to learn how to install and use the SDK.

If you are building you integration in a language other than Python, you can still learn Evo programming concepts by visiting the link above.