API calls no longer friendly to Upchain users.

[matthew_mcvay]

on the swagger page https://live.upchain.net/swagger-ui/index.html#/user/getUserTasks, making a GET call to the https://live.upchain.net/api/user/v1/tasks endpoint results in an Error 403: "message": "Request is forbidden due to whitelisting policy". Something significant has changed since July that has made API calls much less friendly to users. It feels like there was an internal miscommunication where someone took away a lot of functionality from users of server-to-server apps, but no one else told that person that server-to-server apps are the only ones supported by Upchain, and that server-to-server apps only use 2-legged tokens.  Something major needs to be fixed in the code for authenticating and accessing API calls.

[tihomir.mescic]

Hi Matthew. Thanks for reporting this issue. If you have any other issues (other then the getTasks API), please let us know.

Background

Recently, we moved to a different authentication mode for our API users. It's part of the wider initiative, but the bottom line is that we now recommend using 2-legged tokens with impersonation when accessing APIs (this was communicationg to all the existing API users that were using the legacy method - 3-legged tokens). In order for this to work, we need to whitelist the clientID so it has access only to a single tenant. Tenant is specified in each API call by using the Upc-Selected-Company HTTP header. Unfortunatelly, this API was missed and it does not have this header in swagger (as the tenant is specified in a non-standard way - using a query parameter companyId). So, calling it in swagger using a 2-legged token is not possible.

Docs with API instructions: https://help.autodesk.com/view/UPCHN/ENU/?guid=UC_API_GET_STARTED

Workaround

Given that this is only an issue with swagger, what you can do is this:

• use a different API client like Postman, Bruno, or call the API from a Python script
• in the request headers, specifiy Upc-Selected-Company header and send the value of your companyId
• (don't forget to specify the X-User-ID)

Fix

The issue is currently being fixed, the missing header (Upc-Selected-Company) will be added to swagger in the next Upchain version, scheduled to be released at the begining of October, 2024.

Hope this helps...

[matthew_mcvay]

I don't think I communicated that very well.  Currently, if you do not have your company ID (UPC-selected-company), the only way to get it is to email Upchain support.  This introduces room for human error.

If a user does not have their company ID, there previously was a way to use a 2-legged token to retrieve their company ID via an API call.  I think this functionality should return.

Calling the https://live.upchain.net/api/auth/v1/companies API from a python script gave the same "Error 403" message as when using the Swagger page, so I'm guessing that the Postman and Bruno tools would also return the same message if the user does not know their company ID.

Does that help clarify?

[tihomir.mescic]

Dear Matthew.

We are aware of this issue, and you are right that this functionality was available previously, with the old way of authenticating.

Background

Before switching to server-to-server apps, the only way to authenticate and get a token was using a 3-legged process. This process produces a 3-legged token and the token itself contains the user ID that was used to obtain the token (in addition to the clientID as well). When calling the /companies API, the API would extract the user ID from the token and return the companies (tenants) that the user is a part of. The response would contain the company IDs. This functionality was not removed, and it still works if you call the /companies API using a 3-legged token (https://aps-stg.autodesk.com/en/docs/oauth/v2/tutorials/get-3-legged-token/). However, obtaining a 3-legged  token now requires an interaction with the user (entering user password) and is problematic if you write scripts (which most people do). This is the main reason we now recommed using 2-legged authorization with impersonation - it's much simpler and easier to use from scripts (script just needs a clientID and secret pair, and no intervention from a human is required).

However, as you correctly pointed out, this prevents the /companies API from working. The issue here is that the clientID represents an app, not a user, and is not associated to a company/tenant in the same way a user is.

Workaround

As a temporary measure, we have changed a way new API user is onboarded. After whitelisting is performed, Upchain support will contact the user with a notification that the clientID is whitelisted and provide the companyID (e.g. "Hey Matthew, your clientID xyz has been whitelisted and your companyID is 123."). This works for now, and I do not really agree that there is much room for human error here.

In addition to getting the companyID via support email, there are some non-user friendly/ugly ways to get companyId without asking support:

 - log into swagger using a 3-legged process (with your user) and then call the /companies endpoint

 - log in with your user to Upchain Web, and in the Network tab of Chrome every request will have the Upc-Selected-Company header - you can see the value of companyId there

Fix

I do agree that we should have an endpoint to obtain companyID from a clientID - we are in discussions how to design this, and the end result will be a fix for the /companies endpoint or a new endpoint to provide this functionality.