REST API Overview
Authentication and authorization
Overview of OAuth
To use Bentley iTwin APIs and SDKs, your application needs the user's consent to access their data. We use OAuth 2.0 to grant access. Follow these steps to set up OAuth 2.0 for your application. For detailed specifications, see rfc6749.
Before starting the OAuth process, you must register your app with the iTwin Platform. During registration, provide basic information such as the app name and redirect URI, which redirects users to the appropriate web server, browser, or native app. If you haven't registered your application, visit the My Apps page to register your application.
To open the My Apps page, click your Profile button in the upper right corner and then My Apps. You must be logged in to see the Profile button.
Note: Service applications without user interaction do not require a redirect URI. Instead, they authenticate using a client secret provided at the end of the registration process. The automatically created user identity for the Service application needs a role assigned to make requests to the iTwin Platform. This is done using the Access Control API. For more information on setting up your service application, see the Authorizing a Service App guide.
Key terminology
Application scopes and user permissions
The iTwin Platform uses a universal itwin-platform scope that allows applications to access all APIs without the need to have individual scope associations. This scope is included as part of the OAuth process to retrieve an access token. For more information, see introduction of itwin-platform scope.
Data associated with your iTwin is kept secure through user permissions using the Access Control API. This API uses Role-based Access Control (RBAC) to determine the permissions available to end users of your application. See the example below.
Example:
You create an application named My App with the itwin-platform scope. You have a user, User A, that wants to create an iTwin through your application. User A must have a role with the itwins_create permission to create the iTwin within your application. While the application has the ability to create iTwins as part of the itwin-platform scope, the end user does not have the appropriate permissions in the role they are assigned, itwins_create. See the Access Control API documentation for information on setting up end-user permissions.
Authorizing your applications
The method of retrieving your access token depends on OAuth 2.0 flow. The authorization flow of your application depends on your application type as well as the ability to keep client secrets secure. The following sections describe the different types of applications and their authorization methods.
Authorize a service application
A service application typically runs in the background or on a server, providing data or services to other applications. For example, in the iTwin Platform, such an application could automatically sync and update an iTwin's design data to reflect latest information. For authorization documentation, see Authorize a service application. For a tutorial, see Authorize a service application tutorial.
Authorize a web application
An application built on a server-side framework, accessed through a web browser over a network. For authorization documentation, see Authorize a web application. For a tutorial, see Authorize a web application tutorial
Authorize a native application
An application designed to run natively on a specific operating system or device, providing optimal performance and integration with system features. For authorization documentation, see Authorize a native or SPA application. For a tutorial, see Authorize a native application tutorial.
Authorize a single-page application (SPA)
A web application that loads a single HTML page and dynamically updates the content as the user interacts with the app, enhancing user experience by avoiding full page reloads. For authorization documentation, see Authorize a native or SPA application. For a tutorial, see Authorize a single-page application (SPA) tutorial.
Refresh tokens
Access tokens have an expiry time. In the iTwin Platform, access tokens expire after 3600 seconds, before which a client needs to request a refresh of the token. Requesting refresh tokens is possible in web and native (desktop/mobile) applications. When requesting a refresh token, you must include the offline_access scope as part of the authorization request. This scope is added to the request as you would add any other scope in an OAuth request. Tokens are Bearer type, which must be specified in your API calls.
Token endpoint: POST https://ims.bentley.com/connect/token
Request parameters:
refresh_token Indicates the type of grant being used. This tells the service you are requesting a new access_token with a refresh_token.refresh_token you include is the same one received from the previous request.