Successfully integrating with the new Token Flex Usage Data API
by Bastien Mazeran, Designated Support Specialist, at Autodesk on January 28, 2019
Before you can successfully integrate with the new Token Flex Usage Data API, please read this article first as it highlights key points and considerations you should be aware of to ensure a smooth onboarding experience with this new API.
Know the user context
This new API requires the use of 3-legged OAuth2 tokens. This authentication method means that to access the API, the login flow requires:
- A user to login
- The same user to give consent to the Forge app to access the CORE resources on the user’s behalf
This is a very important piece of information, because the user context is what determines which CORE data you can query or export with the API.
As an example, if you authenticate with an Autodesk ID associated to a user with software coordinator role, you will only see the data that user can currently access through the Accounts portal.
In other words, you should access the API with a user that has the same level of access to the data in the Accounts Portal, as you would want through the API.
Linking your Forge Account to your Token Flex agreement
Before reading on, I recommend you review this blog post that defines some Forge-account-related terms that are frequently confused. However, if you’re rushed for time, the most important point to remember is this:
Your development team will almost certainly be creating more than one Forge-based application. Each application that they create should have a corresponding app entry created for it in your Forge portal. (This is to ensure the data you store on the Forge server is segregated by application – which is very important for your application security – read this other blog for more about these security considerations).
The main administrative task for your Forge account will be managing these apps, and passing the app credentials (called API keys) to the developers writing your Forge-based application.
Setting up your Token Flex Forge account
Your Forge account can only have a single owner, i.e. it is associated with a single Autodesk ID. Therefore, you must decide which will be the one and only Autodesk ID (associated with a corporate email) for which you create the TokenFlex linked Forge account
The two ways to setup a Forge account for your company are:
- Use one person’s email address to create the Autodesk ID to be used with your Forge account. This one person will then be responsible for administering the Forge account and apps.
- Create an Autodesk ID using a group email alias, so that multiple people can administer the account. (Do not turn on 2-factor authentication if you’re using a group email alias or you will be tied to one person’s phone number).
The second way gives you more flexibility. Read Item #1 in our API Key Security Considerations blog post to help you decide how many people should have access to your account.
At this point in time, your Forge account is linked to your TokenFlex agreement.
Merging Forge accounts
If someone in your company creates their own Forge account – either by starting a trial or by buying a subscription – then their Forge consumption will not be shown in your TokenFlex consumption report.
If this happens, and the account has applications that you wish to preserve, then you should ask your Customer Success Manager (CSM) to arrange to transfer the Forge apps from the rogue account to your TokenFlex linked Forge account. To do this, please email your CSM the emails of both accounts along with the client IDs of the relevant Forge apps. This will allow the rogue developer to continue to access any data they have uploaded to the Forge servers, while allowing their future Forge usage to consume tokens.
If you have added Forge to your TokenFlex agreement, please read on the section below.
Monitoring Forge consumption (Optional)
The people you have granted access to your Forge account (via the email alias you used to create it) can view your Forge token consumption (broken down by API) in the Forge Usage Dashboard when you are logged into the Forge portal with your TokenFlex linked Forge account. You can also view your aggregated Forge token usage in CORE reporting.
When reviewing your Forge usage, it is important to understand that only some Forge APIs consume tokens – and most do not. At the time of writing, these are the only three actions that consume tokens:
- Translating a model using the Model Derivative API (the POST job endpoint).
- Running an WorkItem using the Design Automation API (the v2 POST WorkItems endpoint or the v3 POST workItems endpoint).
- Generating a 3D mesh from a photoset using the Reality Capture API (the POST photoscene/:photosceneid endpoint).
The token consumption of these operations is documented on the Forge pricing page (where one Cloud Credit equals one Token).
This can be a cause of confusion, because someone may be making a huge number of Forge API calls from their application, and yet be consuming no tokens at all. For example, uploading files to BIM 360 Docs using the Data Management API does not consume any tokens. Therefore, my application could upload thousands of files to BIM 360 Docs, and I would see zero Forge token consumption.
And since this article focused on the new Token Flex Usage Data API, please note that this API is cost free for all TokenFlex customers.