Authorize a Service Application - Tutorials

Introduction

When building a server-side app that securely stores secrets, use the following procedures to set up your authorization. This tutorial is based on the OAuth workflow, diagram, and steps described in the service app authorization documentation.

Register your application

The first step for authorizing your service app is to register your application.

If you have not created an application, open the My Apps page under your Profile menu, and click the Register New button. In this case, the application type is Service.
Make sure to save the client_id and the client_secret supplied when you create your application.

IMPORTANT

Keep your client credentials, i.e., client ID, client secret, and access tokens, secure. Do not include them in publicly accessible code where they could be discovered. Instead, store them safely on a backend server.

Note

Service apps need permission to access the your iTwins or iTwin-related data. You can set up iTwin roles and permissions using the Access Control API and the generated email on the App Details page in My Apps > App Name. Setting up access control is not required for this tutorial; however, it must be set up before your application makes iTwin specific API requests.

Obtain an access token

Once you have your app registered, you can obtain an access token by following these steps:

Send a request to the authorization server endpoint.

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

Below is an example request along with required parameters. You can obtain the client_id and redirect_uri from your app registration on My Apps. If you didn’t save your client_secret, generate a new one from the same app registration.

Your application can now use the access token returned by the token endpoint to access APIs.

Use your token

If you received a 200 OK response to your token request, you have successfully obtained a token. You can use this token to call various iTwin Platform APIs. You can try making an API call to users/me endpoint to test your token. On success, this request returns the profile information for the user account associated with the token received.

Remember, the iTwin Platform Base URI is api.bentley.com.

Client

If you're developing a service application and need to handle service authentication, you can utilize a TypeScript client specifically designed for this workflow. This client is available in the iTwin auth-clients repository and can be easily integrated into your project via the npm package @itwin/service-authorization.

More resources that you may like

Access Control

Manage Access Controls for your iTwin member using iTwin roles and permissions.