OVERVIEW

Bentley SYNCHRO APIs and SDKs require the end user to give consent to your application to retrieve and use data on user's behalf. Our APIs use OAuth 2.0 to allow applications access to the data. The following instructions contain information on how to setup your application to use OAuth 2.0. You can find the detailed specification for OAuth 2.0 at rfc6749.

Before you can begin the OAuth process, you must first register a new app with the SYNCHRO 4D Platform. When registering a new app, you will need to provide basic information including the application name, and redirect URI to be used for redirecting users back to the appropriate web server / browser / native app. If you haven't already, click here to register a new application before proceeding.

KEY TERMINOLOGY

The following key terms are important to know when using OAuth 2.0:

Access Token – a token which contains a string that can be used to make authenticated requests to an API to access protect resources. The string has no meaning to the application using it, but represents that the user has authorized the application to access their account. The token is bounded by an appropriate lifetime, scopes, and other information that the server may require.

Authorization Server – the authorization server validates the identity of the user and then issues access tokens to the app to grant access to protected resources on the user's behalf.

Client – an application which is attempting to access protected resources on behalf of the resource owner (such as the end user). The client can be hosted on a server, desktop, or mobile device.

Client ID – a unique public identifier for an app.

Client Secret – a random string that is known only to the application and the authorization server. The client secret is required for authorizing confidential clients for preventing the authorization server from providing tokens to rogue apps.

Confidential Client – Clients which have the ability to maintain the confidentiality of the Client Secret. Typically, these clients run on a server under the control of the developer, where the source code and configuration is not accessible to users (web server application).

Public Client – Clients that do not have the ability to maintain the confidentiality of the Client Secret. Mobile, desktop and browser apps are typically considered public clients. In all of these cases, the secret should not be used because it can be easily discovered by other developers.

Redirect URI – the Redirect URI is used by the authorization server to redirect the user back to the application with authorization code after the user has successfully authorized the app.

Scope – OAuth 2.0 scopes provide a way to limit the amount of access that is granted to an access token. This can include limiting which protected resources can be access and what level of access (i.e. READ / WRITE) is granted. If a client tries to call an API endpoint and does not include the appropriate scopes, the call will fail with a 401 Unauthorized response.

ERROR RESPONSES

The Authorization Server provides standard HTTP status response codes in the response header.

• A 2xx type response typically represents a successful response.
• A 4xx type response typically represents a client error.
• A 5xx type response typically represents a server error.

The following errors may occur when submitting a request for an access token:

• 400 – Bad request. Common causes include:
  • The given authorization code is not valid or was already used.
  • The redirect_uri differs from the one registered for your client..
• 401 – Unauthorized. Common causes include:
  • The specified client ID is invalid.
  • The token is not valid (has expired).
• 403 – Forbidden. The client down not have access rights to the resource.
• 429 – Too many requests. The application's rate limit for the resource has been exhausted.
• 500 – Internal Server Error. This is typically indicative that the endpoint is temporarily unavailable.
• 502 – Bad Gateway. This indicates that the server got an invalid response.

Other OAuth protocol errors can be returned to redirect_uri in an "error" parameter:

• invalid_request - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
• unauthorized_client - The client is not authorized to request an authorization code using this method.
• access_denied - The resource owner or authorization server denied the request.
• unsupported_response_type - The authorization server does not support obtaining an authorization code using this method.
• invalid_scope - The requested scope is invalid, unknown, or malformed.