Skip to content

Blog

Understanding iTero Authentication: User Tokens vs. Account Tokens

When integrating with the iTero platform, it is important to understand that the authentication flow issues two different types of tokens, each designed for a distinct purpose. Designing your application around the intended usage of these tokens will improve security, reliability, and long-term maintainability.

Two Tokens, Two Different Roles

The iTero authentication flow provides:

  1. User Token – Represents an authenticated iTero user.
  2. Account Token – Represents an iTero account and serves as a machine-to-machine token.

Although both are part of the authentication process, they should be treated very differently by third-party applications.

The User Token: Authentication and Account Discovery

The first token generated during authentication is the User Token.

Its primary purpose is to:

  • Authenticate the user as a valid iTero user.
  • Identify the user's account.
  • Determine the geographical location of the account.
  • Enable the generation of an Account Token.

The User Token should be viewed as a transitional step in the authentication flow. Once it has been used to obtain the Account Token, it should not be used again for API operations.

Important Upcoming Change

To further strengthen security, the refresh token associated with the User Token will soon be limited to 18 hours.

Because of this change, applications should avoid relying on the User Token for ongoing API access. Instead, they should exchange it for an Account Token and use that token for all subsequent interactions with the iTero platform.

The Account Token: Your Long-Term Integration Token

The second token generated during the authentication process is the Account Token.

Unlike the User Token, the Account Token is designed to act as a machine token and should be used for all API communication with iTero.

What Can the Account Token Be Used For?

The Account Token can be used to:

  • Call iTero APIs.
  • Support automated workflows and background processes.
  • Enable system-to-system integrations.
  • Eliminate the need for repeated user authentication flows.

This token is intended to be the primary token used by your integration after initial authentication has been completed.

Refresh Expiration Behavior

The Account refresh Token has an extending refresh expiration model.

This means that as long as the token continues to be actively used, its refresh expiration is extended to 3 months. This behavior supports long-running integrations and automated systems that require persistent connectivity to the iTero platform. If the token is not active for 3 months it will expire.

Sharing Account Tokens Within Your Organization

A common question from partners is whether every user must complete an authentication flow and maintain their own Account Token.

The answer is often no.

Because the Account Token represents an account rather than an individual user, a single administrator can generate the token and securely distribute it within the organization's application infrastructure.

This approach is possible because:

  • The token is intended for machine-to-machine communication.
  • Third-party applications are expected to follow industry-standard security practices for protecting credentials and tokens.
  • The token can support organization-wide integrations without requiring frequent user involvement.

As a result, many integrations do not require every user to authenticate individually.

Token Revocation Remains Available

Even though the Account Token is designed for long-term use, it can still be revoked.

If a token is revoked:

  • The existing token can no longer be used.
  • A new authentication flow must be completed.
  • A new Account Token must be generated.

This provides organizations with the ability to respond to security events, credential rotation requirements, or administrative changes when necessary.

Design Recommendations for Third-Party Applications

When building an integration with iTero, we recommend the following approach:

  • Use the User Token only to authenticate the user, identify the account's region, and obtain an Account Token.
  • Do not use the User Token for ongoing API operations.
  • Use the Account Token for all API calls and automated processes.
  • Store Account Tokens securely using industry-standard security practices.
  • Design long-running integrations around the Account Token's extending refresh expiration behavior.
  • Build processes to handle token revocation and re-authentication when required.

Final Thoughts

The iTero authentication model separates user authentication from ongoing API access. The User Token establishes identity and account context, while the Account Token enables secure and scalable machine-to-machine communication.

Understanding this distinction is essential when designing integrations that are secure, resilient, and capable of supporting long-term automation. By treating the User Token as a one-time authentication mechanism and the Account Token as the operational integration token, third-party applications can take full advantage of the iTero platform's authentication architecture while maintaining strong security practices.

Smoother Integration Ahead: The Benefits of iTero API Migration

Introduction

To strengthen our partnership and drive innovation, we are migrating the iTero solution to enable your applications to integrate with iTero platforms in a more flexible manner and utilize our resources more efficiently. This transition opens new opportunities for flexibility and scalability, allowing you to invest less in maintenance and more in delivering superior customer experiences.

What's Changing & Key Benefits

The migration introduces key enhancements designed for stability and ease of use:

  • Stable Service URL: New, permanent service URLs are being introduced, ensuring consistency despite future infrastructure changes. This builds a more reliable and resilient integration.

  • Automatic Region Detection: Discovery endpoint now dynamically provides region-specific routing (it returns the domain and path), the automatic region detection to guarantee consistent performance.

  • Longer-Lasting Tokens: Refresh tokens remain valid indefinitely, provided the associated account shows at least some API activity every three months.

  • Streamlined File Downloads: The file download functionality is now integrated directly into the Get Orders and Get Order By RXID responses.

Conclusion

These updates are intended to establish a more stable integration, significantly lowering the maintenance required as the platform evolves.

Next Steps Guidance

Migration is currently in progress. Should you have any questions, please do not hesitate to contact us: iteroapisupport@aligntech.com.

Note

This migration does not apply to China at this stage.


Upcoming change for all partners using iTero Generic API

A mandatory change that will happen in the near future is the move from OAuth2.0 to Auth0.

All Partners will have to move to Auth0 to continue using the iTero Generic API.

iTero will make an initial announcement with the details of the change and what's necessary to update. During the transition period, both OAuth2.0 and Auth0 will be supported concurrently. This dual support is designed to give partners ample time to make the switch without disrupting their operations.

Deadlines for the move will be shared when the information becomes available. It is important to stay vigilant to the iTero newsletter and plan your transition accordingly to avoid any service interruptions

Any questions or concerns can be addressed to the official support email: iteroapisupport@aligntech.com

Note

New partners that wish to create a connection with iTero should keep in mind that an additional overhead will be required for the integration to move from OAuth2.0 to Auth0 in the future.


New Feature - Delete Rx

Image


RX is the first step for a successful scan. You can create an RX directly from the scanner or from a DPMS with an iTero connection.

It is a good practice to store each RXID returned by the Scan Request endpoint. This allows you to match incoming scans to their corresponding RX.



What if an RX is created but never used?

With the new Delete RX endpoint, you can now delete RXs directly from the DPMS, ensuring consistency between the DPMS and the scanner. An RX can also be deleted from the scanner that created it.

To delete an RX, use the following DELETE operation on the scan-request endpoint:

DELETE /api/third-party/v2/scan-request/:RXID

Simply pass the RXID, and the endpoint will remove the RX.

Note

RXs can be deleted. However, scans can't be deleted.

If you’d like to try this feature and don’t have access to a scanner, you can use the iTero portal at myitero.com to view and test RX deletions. Any deleted RX will be removed from the orders dashboard.

New Feature: Discovery API - Regional URL's for API calls

We're pleased to announce that V2 of iTero's Generic API can now implement Discovery API.

Discovery API prevents regional problems like ISP routing from affecting the end user experience and integration functionality. This helps prevent issues like false 'not paired' messages, orders not found, and more.
The regional value returned is retrieved from the clinic's or lab's address in the internal iTero system.

Image