Authentication

The Authentication & Pairing process is the first step in 3^rd party software integration.

Upon completion of this step, the caller receives an access token, to be used as authorization key for all Align generic APIs

Definitions, Acronyms, and Abbreviations¶

Term	Description
Myitero.com	iTero portal to manage account and cases
Production environment	Live environment
Redirect URL	URL to which the response should be returned
Access Token	Security credentials key for login session and user identification
Callback URL	URL to which a notification is sent upon scan completion

Authentication & Pairing Overview¶

Authentication and pairing are required to be completed before using Align APIs. Upon completion, the 3^rd party software can be integrated with iTero software.

Align authentication API complies with OAuth 2 Authorization Code Grant. For more information, please visit:

https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/

Required Customer Information¶

To create an account in the authentication server, a company must provide Align the following information:

Company Name
Redirect URL: After a user successfully authorizes an application, the authorization server will redirect the user back to this URL

This URL should be whitelisted on iTero side
It should use https
iTero doesn't support URLs with "#' in them

Provided Authentication Information¶

The following will be provided by iTero support:

The application ID that is assigned to your app <ClientID>
The application secret assigned to your app <ClientSecret>
MyiTero.com Credentials
Server URL for authorization process – shown as {{oauthBase}}
Server URL for pairing process – shown as {{baseUrl}}
Align Login Page – shown as {{loginPage}}

Authentication and Pairing Process¶

The Authentication and Pairing process consists of three steps:

Authentication process - concludes with access and refresh tokens
Discovery - returns regional URL's to use for a given account
Get available companies for pairing using returned token
Pairing to a chosen account - concludes with pairing to a selected account and new access and refresh tokens to use iTero APIs

The authentication process can work for a sever to server configuration or sever to client configuration. The token (after pairing) is associated with an account (and not with an individual user) such that in case of server to server configuration, the token can be securely stored by the 3^rd party and shared by the callers. For client applications, the token will have to be stored at the client.

The advantages to use this mechanism are:

Higher level of security
Pairing is based on account and not on user. Account’s users may change with time.

In case a server is not available to the account, both sets of tokens can be managed on the client side, however this option is less preferable.

Please refer to the chart at the end of this document for a graphical view of the process.

Note

All users of the account will share the same tokens after pairing.
Full authentication process is required when refresh token expires (valid for one year). As long as refresh token is valid and securely stored it is not necessary to repeat this process (however, there is no harm doing so).

Once the pairing process is completed, the 3^rd party will be able to use Align APIs for the paired company.

Authentication Process¶

Authentication process returns Access and Refresh Tokens that are later used for all API calls.

Authorization code grant request¶

The 3^rd party software should call the authorization page URL, based on the following:

{{oauthBase}}
Client_ID received from iTero Support
State - Optional 3^rd Party choice random string
Redirect URL
{{loginPage}}
Scope - openid
Prompt - login

Add the client ID received from iTero Support, and the redirect URL.

{{oauthBase}}/oauth2/authorize?client_id=<Client_ID>&response_type=code&state=<string>&redirect_uri=<Redirect URL>&loginPage={{loginPage}}&scope=openid&prompt=login

A Login page will open; enter your MyiTero.com credentials.

Login

Figure 1: Enter your iTero credentials

The user will be redirected to the following address:

<RedirectURL>?code=<AuthorizationCode>&state=<string>&session_state=<string>

The 'code' parameter (auth code) in the URL is used in the next step, alongside the state parameter for added security.

Using State Parameter¶

For extra security, a 3^rd party partner can use the state parameter with a random value that is sent with the authorization request and can compare it to the returned state parameter. Code values should be identical.

Exchange the authorization code for an access token¶

To exchange the authorization code for an access token, POST the following call using only raw format (This endpoint doesn't accept JSON):

{{oauthBase}}/oauth2/token

Headers

‘Content-Type’: ‘application/x-www-form-urlencoded'

Request body

code=<AuthorizationCode>
grant_type=authorization_code
client_id=<ClientID>
client_secret=<ClientSecret>
redirect_uri=<Redirect URL>

Provide the authorization code that was returned in the previous step.

Note

Auth code should be used immediately. It will expire within a few minutes.
The returned Auth code is single-use only.

Response

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
400	Bad request	1. Wrong code 2. Missing code	Double check if call used the correct authorization code
401	Unauthorized error	The client is not authorized to perform this operation	Check if call is using the correct credentials
500	Internal Server error	/	A retry mechanism is recommended for this error message
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

In case of returned code of 200, the following response will be returned:

The call returns access and refresh token with 1-hour expiry, and a refresh token that lasts for 1 year.

See response example below:

{
    "access_token": access token,
    "refresh_token": refresh token,
    "scope": "openid",
    "id_token": token ID,
    "token_type": "Bearer",
    "expires_in": 3600
}

Below is a table describing the information that has been returned in the Data section of the response:

Field	Type	Description
access_token	String	Access token to be used in APIs as a bearer token. Its size is up to 8K.
refresh_token	String	Refresh token to be used when access token is expired. Size is up to 40 characters.
scope	String	openid
Id_token	String	Cached user profile
token_type	String	Type of token: Bearer
expires_in	Number	Number of seconds left before token’s expiration. Initial value is 3600 (one hour)

Refresh Token Request¶

Callers should exchange a refresh token for an access token when the access token expires.

This allows keeping a valid access token without further interaction with the user.

To refresh an existing token, POST the following call:

{{oauthBase}}/oauth2/token

Headers

'Content-Type’: ‘application/x-www-form-urlencoded'

Request body

refresh_token={{refresh_token}}
grant_type=refresh_token
client_id=<ClientID>
client_secret=<ClientSecret>

Response

Response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
401	Unauthorized error	1. Wrong refresh token 2. Missing refresh token	Double check that call is using the correct refresh token
500	Internal Server error	/	A retry mechanism is recommended for this error message
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

In case of returned code of 200, the following response will be returned

The response includes a new access token with 1-hour expiry, while the refresh token remains the same.

{
    "access_token": string,
    "refresh_token": string,
    "scope": string,
    "token_type": string,
    "expires_in": number
}

Response keys are identical to the keys in the first-time token request.

Refresh Token Expiry¶

Refresh token can be used for one year. Upon expiration, the 3^rd party app should make sure to trigger a new authentication request as described on the Authentication Process.

Note

Coupling "Refresh Token" call with a call to "Discovery" endpoint is recommended. In rare cases of changes in the domain or URL, the change will be automatically adopted by the 3^rd party app, once the refresh is called. Refer to discovery API below.

Revoke token request¶

The Token Revocation extension defines a mechanism for partners to indicate to the authorization server that an access/refresh token is no longer needed. This is used to enable a "log out" feature at the client side, allowing the authorization server to clean up any security credentials associated with the authorization.

Note

Token revocation will deprecate the refresh token. The next time a token will be requested,a new refresh token will be returned
Do not revoke the token unless:
1. The current token is no longer required
2. The current token was compromised
3. It is decided by design to proactively generate a new refresh token

To revoke an existing token, POST the following call:

{{oauthBase}}/oauth2/revoke

Headers

'Content-Type’: ‘application/x-www-form-urlencoded''

Request body

Options response codes are:

HTTP Status	Code	Description	Scenario	Recommendation
200	OK	/	/	/
401	Unauthorized error	1. Wrong token 2. Missing token	Double check that call is using the correct refresh token	/
500	Internal Server error	/	A retry mechanism is recommended for this error message	/
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

In case of returned code of 200, the following response will be returned

token={{access_token or refresh_token}}
token_type_hint={{'access_token' or 'refresh_token'}}
client_id=<Clientid>
client_secret=<Clientsecret>

Discovery - Regional URL's for API Calls¶

Introduction¶

iTero services are regional, meaning that a caller should access his region in order to retrieve its account data. A highly recommended practice is to use endpoint "Discovery".

Benefits¶

iTero APIs are based on regional location. Each account is paired in a specific region and the calls are expected to be routed to that same region. DNS geo-based routing does not always route the caller to the correct region. With the regional base URL, the calls are guaranteed to go to the correct region.
End users can work from outside their permanent address. Caller app will be routed to the correct region in cases where it is outside its intended geographical region, such as a business trip or other scenarios.
The returned URL is regional. This makes sure that the caller access the correct region. This mitigates call failures due to wrong calls routing, which sometime happen by the different ISPs (Internet Service Providers).

When to use¶

A call to this endpoint should happen in two point in time:

After the initial authentication is completed and before pairing
With every call to refresh token

The first call should use the first generated token before pairing. This will ensure to use the correct regional URL, based on the location of the caller in iTero back office system (not geolocation).

The second case is to ensure to accommodate any future changes in the URL or domain (not likely to happen).

A simple use case would be:

A call returns 403 (Because access token has expired)

Make a call to Refresh Token

Make a call to "Discovery"

Resume initial call to the iTero API and continue normal usage.

Note

iTero operates in four regions:

North America
Europe
Asia Pacific
China

How to use¶

The "Discovery" endpoint returns the regional base URL that must be used for all of future API calls.

The future calls will follow the overall structure: Domain/Path/endpoint

The first call to discovery is made with the {{baseUrl}}, but subsequent calls must be made with {{Domain}}/{{Path}} returned by discovery

Which endpoints do not use Discovery?

Authorization endpoints:

Authorize
Authorization Code
Refresh Token
Revoke Token

Which token should I use for Discovery?

The first call to discovery, since the user is not paired to any company, should be done with the access token

After pairing, "Discovery" should be called with the pair access token

Discovery Structure¶

Send a GET call to get the relevant Domain and Path of the iTero APIs.

First call: {{baseUrl}}/api/third-party/v2/api-discovery-by-name-and-version?discoveryName=thirdparty&version=2

Subsequent calls: {{Domain}}/{{Path}}/api-discovery-by-name-and-version?discoveryName=third-party&version=2

Header

Authorization: The access token received after the initial authentication step is provided as a Bearer Token authorization type.

Parameters

Call parameters must include the following mandatory fields and exact values:

Parameter	Value
discoveryName	third-party
version	2

Response

HTTP Status	Code	Description	Scenario	Recommendation
200	False	OK	Empty Array	An empty array can mean one of two things: 1. You've not yet requested access to the "Discovery". Therefore, your request will not be processed. 2. The parameter values are incorrect, and since the resource does not exist, you get back an empty response.
200	OK	One entry in array	Correct behavior	/
400	Bad request	Wrong asset format	Double check the parameter fields and values	/
401	Unauthorized error	1. Wrong token 2. Missing token	Double check that call is using the first access token (Returned after Authorization Code endpoint), or, refresh the access token for a new one using 'Refresh Token' endpoint.	/
500	Internal Server error	/	A retry mechanism is recommended for this error message.	/
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

Return Body General Structure

{
    "APIs": [
        {
            "Name": "third-party",
            "Version": "2",
            "Path": "/itero-gen-api/v2",
            "Domain": "regional URL"
        }
    ]
}

Description of the returned body

Fields	Description	Notes
Name	Name of the service	All 3^rd parties consuming iTero Generic API will get 'third-party'
Version	Service version	3^rd parties consuming iTero Generic API will receive the API version they use (2 in most of the cases)
Path	The path for all APIs	All API calls should use the Domain/Path/endpoint
Domain	The Domain of all APIs	All API calls should use the Domain/Path/endpoint

Get Available Companies for Pairing¶

Send a GET call to get a list of all related accounts of the current user:

Title	URL
Discovery	{{Domain}}/{{Path}}/related-accounts
Legacy	{{baseUrl}}/api/third-party/v2/related-accounts

Header

Authorization: The access token received at the end of authentication process is provided as a Bearer Token authorization type.

Options response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
401	Unauthorized error	1. Wrong token 2. Missing token	Double check that call is using the correct access token
500	Internal Server error	/	A retry mechanism is recommended for this error message.
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

In case of returned code of 200, the following response will be returned

This GET request returns a JSON format containing the related companies’ IDs, names and addresses.

The listed accounts meet the following criteria:

The user is related to these accounts
The account is enabled for that specific integration.

Both are configured in Align system. If one of the conditions is not met, the account will not be listed and cannot be paired to by the user.

{
    "Data": [
        {
            "AccountId": number,
            "AccountName": string,
            "AccountAddress": string,
            "IsPaired": true/false
        }
        ...
    ],
    "Status": // Success, Failure
    "Errors": [
    ] // array of errors if Status = Failure
}

Below is a table describing the information that has been returned in the Data section of the response:

Field	Type	Description
AccountId	String	ID of related account
AccountName	String	Name of related account
AccountAddress	String	Address of related account
IsPaired	Boolean	True if the account is already paired with the user. To unset this field callUnPair endpoint

Company Pairing¶

Pairing process pairs the user to a selected account and returns a new set of access and refresh tokens. In case the user is already paired to the company, calling pair request will return the same refresh token that was generated before

Pair request¶

To pair the user with the selected company from the list above, use the following PUT call:

Title	URL
Discovery	{{Domain}}/{{Path}}/pair-account
Legacy	{{baseUrl}}/api/third-party/v2/pair-account

Headers

'Content-Type’: ‘application/json'

Authorization: The access token received at the end of authentication process as a Bearer Token authorization type.

Request body

{
  "AccountId": number,
  "CallbackUrl": string
}

Request body includes:

AccountId of the account to pair to
CallbackUrl is a valid URL to which push notification will be sent. An order that is ready will trigger a notification sent to the the notification URL.

Response

Options response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
400	Bad request	Wrong companyid	Double check if call uses the wrong companyid
401	Unauthorized error	1. Wrong token 2. Missing token	Double check if call is using the correct access token
409	Conflict	A paired account is trying to pair with a different 3^rd party app	This is applicable for labs only. Lab accounts cannot have multiple pairing for 3^rd party applications. In this case the lab should first unpair from the old integration and then pair to the new integration.
500	Internal Server error	/	A retry mechanism is recommended for this error message.
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

In case of returned code of 200, the following response will be

This PUT request returns a JSON format containing the second access and refresh tokens, and time left for expiration.It is important to note that from this point on, these set of tokens must be used. To maintain these tokens, the same refresh and revoke endpoints mentioned before apply.

{
    "Data": {
        "OAuthResponse": {
            "access_token": string,
            "refresh_token": string,
            "scope": string,
            "token_type": string,
            "expires_in": number
        },
        "CompanyId": number
    },
    "Status": 1
}

Check Patients Information Coherence (Applies only for DPMS solutions)

Pairing request will return a warning in case there are multiple patients in the system with the same chart number or patient missing chart number. Please refer to API Specification for more details.

{
    "Data": {
        "OAuthResponse": {
            "access_token": string,
            "refresh_token": string,
            "scope": string,
            "token_type": string,
            "expires_in": number
        },
        "Warnings": [
            "Empty or duplicate patient identifiers (chart#) exists

             in iTero patient database"
        ],
        "CompanyId": number
    },
    "Status": 1
}

Unpair account request¶

To unpair a user from an account call this DELETE request:

Title	URL
Discovery	{{Domain}}/{{Path}}/unpair-account
Legacy	{{baseUrl}}/api/third-party/v2/unpair-account

Headers

The access token received at the end of pair request as a Bearer Token authorization type

Request body

{
 "AccountId": number
}

Body includes AccountId of paired account.

Note that since the pairing is based on account, un-pair will affect all paired users to this account, and all will be un-paired. Also, the callback URL will be deleted for the account.

Note

There is no need to unpair the account unless one wants to discontinue the service or upon a few special cases.
Therefore, it is recommended to implement an unpair option in the 3^rd party application. This option should be available upon permission to the designated personnel.

Response

Options response codes are:

HTTP Status Code	Description	Scenario	Recommendation
200	OK	/	/
400	Bad request	Wrong companyid	Double check if call used the wrong companyid
401	Unauthorized error	1. Wrong token 2. Miss token	Double check if call uses the correct pairing access token
500	Internal Server error	/	A retry mechanism is recommend for this error message.
504	Gateway Timeout	Timed out	Retry the request after a brief wait time (1000ms)

Scan Notifications¶

Scan notifications is a mechanism that implements a webhook to notify the account that a new scan is ready. This mechanism can be used in exchange or in addition to the polling mechanism of Get Orders. Please check for more details in DPMS API Specification (for clinics) or on Lab Connector API Spec (for labs).

Note:

A third party can choose to register an integration-wide URL with Align to which notifications will be sent. This URL will apply to all accounts that are associated with this integration.
If no URL is provided by the third party, it can be provided during paring request. This will apply to the account that is paired.
If both URLs are provided, the notification will be sent to the third party's integration-wide URL and not to the one provided in the pairing call.
If not URL is provided, a notification will not be sent.
If a third party is not using an integration-wide URL and wishes to change the URL listed in the Pair endpoint, the account must unpair, and then repair with the new callback URL.

Authentication & Pairing Sequence Diagram¶

The following table shows the authentication and pairing APIs integration diagram:

Diagram

Figure 2: Authentication & Pairing Sequence Diagram

Authentication

Definitions, Acronyms, and Abbreviations¶

Authentication & Pairing Overview¶

Required Customer Information¶

Provided Authentication Information¶

Authentication and Pairing Process¶

Authentication Process¶

Authorization code grant request¶

Using State Parameter¶

Exchange the authorization code for an access token¶

Refresh Token Request¶

Refresh Token Expiry¶

Revoke token request¶

Discovery - Regional URL's for API Calls¶

Introduction¶

Benefits¶

When to use¶

How to use¶

Discovery Structure¶

Get Available Companies for Pairing¶

Company Pairing¶

Pair request¶

Unpair account request¶

Scan Notifications¶

Authentication & Pairing Sequence Diagram¶

Verify CAPTCHA