REST API Overview

Authorize a service application

Service applications are designed to access web-hosted resources without user interaction. They operate using the application's identity and run on a server where the source code or configuration is not publicly available. This setup allows the use of a client secret when communicating with the authorization server. This form of authentication is known as two-legged OAuth, in contrast to three-legged OAuth, which involves user interaction for consent.

The service application type does not represent any user or organization and does not have access to any project data by default. To grant access to projects, you need to invite it using the client email provided on the App Details page after you register the application.

Client Credential Flow

The Client Credential Flow allows your backend process or service, i.e., a confidential client, to authenticate using its own credentials rather than impersonating a user. An administrator grants permissions directly to the application. Since no user is involved in the authentication, the resource enforces that the application is authorized to perform an action when it presents a token to a resource.

The following steps provide an overview of the process.

The application makes a request to the authorization server token endpoint with the required parameters.
The authorization server confirms the information supplied and returns an access token.
The application uses the access token to call a given API.
The API responds to the request with the requested data when the necessary scopes are included in the token, and the service identity has the proper permissions for that API.

sequenceDiagram
    participant app as Application
    participant as as Authorization Server
    participant api as iTwin API

    app->>+as: Authenticate using client_id and client_secret
    as->>as: Validate client_id, client_secret and scopes
    as->>-app: Granted access token

    app->>+api: API request with the access token
    api->>-app: API response

Set up authorization for your app

The following steps outline how to implement the authorization code flow in your application. Once you have registered your app, you can begin to obtain the access token.

Send a POST request to the authorization server endpoint.

POST https://ims.bentley.com/connect/token

The authorization request requires the following parameters:

grant*type

Set to client_credentials for service-based applications.

client*id

The ID of the app you created. If you forgot the ID, find it on the My Apps page. Locate your app in the list. The Client ID is in the same-named column.

client*secret

The secret given when you registered the app. If you did not save the client secret, generate a new one. To do so, open the My Apps page and find your app in the list, click the link to open the details page, and then click Re-generate in the _Client Secret* field.

scope

Add the itwin-platform scope assigned to your app during registration.

The authorization server confirms the client_id and client_secret and returns an access token. Bentley's authorization server completes this step. There is no implementation needed in your application. A successful response includes the access token.
Use the access token to call the API. Remember to call iTwin Platform APIs, you must set up your iTwin roles and permissions. For more information, see the Access Control API documentation.

Token request example

curl https://ims.bentley.com/connect/token -X POST --data-urlencode grant_type=client_credentials --data-urlencode client_id=<client_id> --data-urlencode client_secret=<client_secret> --data-urlencode scope=<scope>