I had a couple of conversations last week with people who were a bit confused about the relationships between Autodesk Ids, Forge Accounts, Apps, and Client Ids. That confusion isn’t surprising, because we 'deskers tend to use several different names to describe the same things (and we often use similar sounding names to describe completely different things). The conversations were different, but similar enough that I felt it worthwhile to put all that information in the same place for the benefit of others. Hence this blog post.
This post is in two parts:
- Definitions of the different types of Ids and accounts that relate to Forge, and
- Some account and API Key considerations for Forge developers.
Definitions:
Autodesk Id
An Autodesk Id is the single account you use to access (essentially) all Autodesk services – you use it to access your product subscriptions, to request support, to interact with your peers on our forums, and to subscribe to Forge. (When you’re asked to sign in using your Autodesk Id, you’ll also be presented with a ‘create account’ option). You manage your Autodesk Id (account) via accounts.autodesk.com.
Sometimes, you may hear someone refer to your Autodesk Id as your customer Id or single sign-on Id.
Forge account
You create your Forge account by clicking the ‘sign-up’ button at developer.autodesk.com. To create your Forge account, you must sign in with an existing Autodesk Id (or create a new Autodesk Id when prompted).
Note: Forge does not appear in your Autodesk Account portal (accounts.autodesk.com) until you have either activated a trial or purchased Forge credits. Once you’ve done that, you’ll see something like this:
Apps
In the context of Forge (not to be confused with the Autodesk Apps Store), an App is a unique pair of API Keys (see definition below) and associated information.
In general, you will create a unique App for every unique Forge-based application you develop. The reason you shouldn’t share Apps (API Keys) between different applications is simple – it limits the potential damage if someone manages to hack your application (i.e. you need only regenerate the Client Secret (see below) for one application, rather than all of them; and the hacker can only access data associated with that particular application).
When creating a new App, you will specify the Forge APIs that the App will use, and then enter an app title, Description, Callback URL, and a URL for your website.
If you create an App before activating a Forge trial or purchasing Forge credits, you will only be able to see and select two APIs: BIM 360 API and Data Management API. More APIs will be available once you’ve activated a trial or purchased Forge credits
API Keys
Once you’ve created your App, you’re taken to a screen that displays your App details. This includes the Client Id and Client Secret for your App. (The Client Id and Client Secret are commonly referred to as API Keys). You need both of these to go through the authentication (OAuth) process to access your data and use the Forge APIs.
Client Id
A Client Id is sometimes called a Consumer Key. It’s a unique key – uniquely assigned to you that allows your application to identify itself in public. It is used during the authentication (OAuth) process, and many developers also use it as a prefix when they have to generate a unique name for something (for example when naming buckets used for file storage in the Object Storage System).
Client Secret
The Client Secret is sometimes called a Consumer Secret Key. It is used in conjunction with the Client Id to authenticate your application. Unlike your Client Id, you must never share your Client Secret with anyone. (The only time you will use it is during the OAuth process). If you accidentally do reveal it to someone, you can regenerate the Client Secret for the App from the Forge App details screen (see image above). The advantage of regenerating your Client Secret instead of generating a completely new App is that this allows you to retain access to the data you have posted to the Forge platform.
Considerations for Developers
Phew! That’s the definitions done with. So now let’s go through a few details you need to consider when creating your Forge account and generating Apps. I’m not telling you what to do here – or even going into a huge amount of detail – I’m just making you aware of some issues you need to think about.
Sharing Autodesk Ids
At the time of writing, a Forge account can only be associated with a single Autodesk Id. You can’t assign multiple users to the same Forge account. This means that whoever owns the Autodesk Id that the Forge account was created for has sole control over that account. This has some implications you need to consider before you create your account …
If you’re the person at your company who manages all your Autodesk subscriptions, and you’re happy to be the only one who can access the Forge account (e.g. to create new Apps, to monitor usage, or to purchase new Forge credits), then go ahead and use your own Autodesk Id to create your Forge account. (Restricting access to your Client Secret keys is a good idea – as a wise man once said, ‘only one person can keep a secret’ :-)).
However, if only one person has access to the account, then this may cause you problems if they suddenly leave your company and refuse to give you the password to their Autodesk Id. Therefore, you might prefer to create an Autodesk Id using an email alias, to which you add as members the (one or more) people in your team who are allowed to access your Forge account.
[Strong hint - Security best practice is to apply the principle of least privilege, so you should restrict access to your API Keys (and hence your account) to as few people as possible - even if that adds a little inconvenience for you. How many people do you share your online banking password with?]
You can also transfer ownership of an Autodesk Id by editing its username, email address and password in the Security Settings tab on accounts.autodesk.com, but this transfers all entitlements associated with that account to the new user – you can’t use this mechanism to reassign your Forge account while keeping your other entitlements. You can transfer an App from one account to another, to do so, please submit a request via forge.help@autodesk.com.
Writing an application for someone else
If you’re developing a Forge-based application that you intend to hand over to someone else (for example, if you’re working as a consultant for a customer), think about how you’re going to hand over that application. You can’t hand over your API Keys to someone else, because they will then be incurring charges against your Forge account. And any data you’ve uploaded to our Object Storage Service (OSS) and translated for viewing can only be accessed using the API Keys that were used to upload it.
You need to decide at what point in the development cycle to ask your customer to create their own Forge account and generate an API Key for you to use. You might do this right at the start, or you might choose a time before they upload/process a significant amount of data.
Segregating data from multiple users
If you write an application that serves multiple users, you need to make sure that one user can’t access data belonging to another user. Getting your architecture wrong could expose customer data accidentally through a bug, or could be exploited maliciously by a hacker.
There are basically two approaches to storing customer data:
- Use a single API Key to store data from all your users in the same place, and enforce separation in your application architecture.
- Assign each user a different API Key.
Option #2 would appear to be simpler. However, even if you assign one API key per user, you must still securely store information about which API key is associated with which user. In addition, API Keys must be created manually, so option #2 is only practicable for a small number of users (and is best suited to an architecture where each user/customer has their own instance of your application).
Tracking a user’s Forge API usage
Forge provides usage analytics for your account, showing daily consumption of Forge credits, categorized as Simple Jobs, Complex Jobs (both for the Model Derivative API), Processing Hours (Design Automation API), and Gigapixels Processed (Reality Capture API). This image shows the dashboard before you've used any Forge credits:
You can track ‘per customer’ usage simply by assigning different API Keys to different customers. After some (and usage), the ‘Cloud Credits Consumed’ will show like the following image:
Or you track Forge credit consumption in your application. This is relatively straightforward, as there are only a few API calls that consume cloud credits:
- Model Derivative API: The POST job endpoint consumes 0.2 credits per translation for simple jobs or 1,5 credits per complex job. (Complex jobs are currently Revit and Navisworks files – all formats are Simple Jobs).
- Design Automation API: The POST workitems endpoint response contains TimeDownloadStarted and TimeUploadedEnded parameters from which you can calculate CPU usage. This blog post focus on Design Automation cost.
- Reality Capture API: You know what files (images) you've loaded, so you can calculate the total number of pixels you uploaded to be processed.
Detailed API pricing information is available here - https://forge.autodesk.com/pricing. If something isn't listed there as consuming Forge credits, then it doesn't.