Python API/Rest API and authentication with SSO enabled

Both our APIs—Python and REST—allow the use of a username/password pair for authentication when connecting to Shotgun, but if a site is using SSO, the username/password method is not allowed.

While this may be surprising, there is a good explanation:

Shotgun is no longer the gate-keeper, and cannot tell by itself if your credentials are valid. This task is now handled by your IdP (Identity Provider, like Azure, Okta, etc.).

(Note: scripts that authenticate with a script_name/api_key pair are not impacted by the use of SSO, it is business-as-usual for them)

When using a browser, Shotgun redirects you to your IdP (using a 302) and then the IdP redirects your browser back to Shotgun once authenticated. Unfortunately, this mechanism is not possible when using a API-based communication. The handshake process between the servers involves Javascript being interpreted and the actual login flow varies across IdPs.

But, can't Shotgun just contact the IdP to validate the credentials?

Unfortunately, no. Depending on your specific network topology, Shotgun may not able to directly connect to your IdP (in fact, our SSO implementation assumes that Shotgun cannot connect directly to an IdP). As well, no IdP offers an API to validate a password as it is a potential security risk.

The key take-away is:

Use of username/password in API calls are inherently insecure and highly discouraged.

So, what are my options to authenticate with the API when SSO is enabled?

Use a web browser—or a browser-like widget—to authenticate and then use the session_id from the browser to initiate an API connection with Shotgun. This is what is done by Shotgun Create, Shotgun Desktop, and RV.

These applications use a special path on the Shotgun server (<SERVER_URL>/auth/renew) to start an authentication process for a user. Once the web widget gets back to the <SERVER_URL>/auth/landing, we know that the login process was successful. The widget is then closed and we fetch the _session_id value from the cookie jar. This is used to create an API connection to Shotgun.

It is assumed that any web page shown to the user is part of the authentication process or is reporting back errors to the users with additional instructions. If the widget is closed without reaching the landing page, then we know the user abandoned the process.

The mechanism used by our applications is available to all external clients, but the simplest way to make use of it is to use Shotgun Toolkit in combination with Shotgun Desktop or Shotgun Create installed on your system to use the existing session.

Additional Background and Context

Shotgun's SSO implementation relies on SAML2.0 as this older standard maximizes the number of IdP we can support. This means we do not have to rely on IdP-specific SDKs or APIs—thereby reducing maintenance and support complexity.

We expect Shotgun and the IdP to know about each other, but we do not rely on direct communications between the two. In order to support the case where Shotgun is hosted on the cloud, but the IdP is hosted internally in the company’s infrastructure. For Shotgun to connect to the IdP, a special firewall configuration would be needed to allow.

Instead, we rely on the client application (e.g.—the browser or the web widget) to be the relay for communications between the two servers. The expectation being that the user’s machine is able to reach both Shotgun and the IdP. This also sheds some light on the absence of server-to-server calls to validate the user’s credentials.

Implementation Examples

Here are two potential examples of ways to proceed that connects to a site and gets the list of projects ( using a username and password when assuming a simple initial Python API script:

Sample 1—Using Toolkit for User Authentication Reference

( We use the toolkit to get a reference to the currently authenticated user and create a new connection to the server (which is the equivalent of a Shotgun() object creating in the Python API). If there are no currenlty authenticated users, we instruct the script invoker to start either the Shotgun Desktop or Shotgun Create and authenticate.

Sample 2—Using Current Toolkit User

( We attempt to use the current toolkit user. If there are none, we create a Qt Application (so that the GUI can be shown, not just command-line prompts), and then ask the user to select a site and authenticate.

These are just simple examples that can easily be modified and tailored to suit the different needs.

They each have pros and cons, and your individual use case will dictate which one makes more sense for you.



Finally, here’s an overview of pros & cons of using Toolkit as opposed the the Python API:

Under the hood, the Toolkit uses the Python API, but a lot of scaffolding and abstraction is built on top of it.

1. Using the Python SDK with username/password

-You can have multiple scripts connecting to different sites with different users at the same time

-SSO is not supported

2. the simple integration with the Toolkit

-Support all current and future authentication mode, as well as handle MFA and other security mechanisms
-The changes to an existing script is minimal (import sgtk, create connection). The rest of the Python API script stays the same

-Can only be connected to the same site as the current Toolkit session
-You need to query which user and site are in play, to get the current context of the connection
-Dependent on another application to initiate the connection (SG Desktop or Create), You do not control the site/user

3. the self-auth integration with the toolkit (as is show in the sample code):

-Support all current and future authentication mode, as well as handle MFA and other security mechanisms
-The changes to an existing script is minimal (import sgtk, create connection). The rest of the Python API script stays the same
-No need to defer to the SG Desktop or Create to initiate the authentication

-Can only be connected to the same site as the current Toolkit session
-You need to query which user and site are in play, to get the current context of the connection
-You need to have PySide/PySide2 available on your machine (which is not that big of a deal if you rely on an existing SG Desktop install)
-Since a GUI is shown to the user to select the site/user, no control over those values
-Loading PySide and creating a QApplication does induce increased startup times


The 3 previous samples I included were using (directly or indirectly via the Toolkit) the Shotgun API.

I have created versions of these, which instead are using the REST API.

The important take-away is that you need a way to get a valid session_token from Shotgun. This can be achieved in a number of different ways, but the common point is that a Web Browser has to be used in that process. Our examples usea Qt, which is used in RV, Create and Desktop. You can use native toolkits for your target platforms, which is what we used for the iOS Review app.

Base sample : (1.4 KB)

Sample 1 : (2.7 KB)

Sample 2 : (2.6 KB)

Assuming that you have in hand a valid session token, and you want to use the Python API, you need to initiate your API session like this:

from shotgun_api3 import Shotgun
sg = Shotgun(<YOUR_SITE_URL>, session_token='<YOUR_SESSION_TOKEN>')
projects = sg.find('Project', [], [])

To see how it is done with the REST API, have a peek at samples 1 and 2.



I would like to add an important note about our dependency on PySide and PySide2…

Unfortunately, different products ships with different versions, and this will impact your ability to connect to a Shotgun site that is using SSO.


  • only version 1.2.2 and up is known to be compatible. And even then, it may be best to use the version bundled with the Shotgun Desktop as apposed to a standalone version or one shipped with another product.
  • based on Qt4, this is very old and going away.
  • the web functionalities are provided by QtWebKit, which is a hard requirement. This is an optional package and it may be absent from your version, which will prevent SSO support.
  • used by the Shotgun Desktop up to version 1.5.9 (version 1.6.1 and later uses PySide2)
  • used by RV up to version 7.3.4 (version 7.5 and later uses PySide2)
  • also used but older applications, but not recent ones
  • only is available for Python2, not Python3
  • there is an NTLM patch applied to versions provided by Autodesk products. It is best to stick to those versions.


  • only version 5.12.1 and up are known to be supported and work. Some version-specific issues may cause problems with the authentication process.
  • version 2.0.0~alpha0 without QtWebKit is NOT supported, no matter if it came from an Autodesk product or another application or standalone.
  • this uses Qt5
  • provides the web environment using QWebEngine, based on Chromium. This is a hard-requirement. This is an optional package, which may not be present in your build. And even when present, must be properly configured.
  • some older version of PySide2 would provide the older QtWebKit. In that case, you will be able to authenticate. But this is a very rare setup, seen in software from 2018 or before.
  • PySide2 is available for Python2 and Python3. The official Qt repository does not offer a Windows version for Python2, but certain applications do.
  • The recent Autodesk applications which offers PySide2 are usually able to support the full authentication flow. Contact our support if you have questions about specific versions.
  • When using the Shotgun toolkit, a recent release of tk-core, version v0.19.16 or more, will be required. You may need to update your configuration.
  • When using the recent versions of RV, Create and Shotgun Desktop, support of SSO will be present.

In short, whenever possible always use the latest version of the application and tk-core.