Authentication Guide for Flow Production Tracking (formerly known as ShotGrid) REST API

Authentication guide for technical users with Python knowledge who want to use the Flow Production Tracking REST API in other languages

This article is targeted at technical users with Python knowledge who want to use the Flow Production Tracking (formerly ShotGrid) REST API in other programming languages. When creating applications for Flow Production Tracking, it's necessary to retrieve information using the API. A challenge in this process is the lack of information about authentication methods for the REST API. This article provides detailed information about Flow Production Tracking (ShotGrid) REST API authentication, with special focus on the less documented User Name/Password authentication.

2. ShotGrid REST API Authentication Methods

2.1 Differences between API3 and REST API

There are mainly two types of APIs for Shotgun / ShotGrid:

API3 (shotgun_api3):
- The traditional API used for Python.
- For usage outside of Python, documentation is limited and source code reference is required.
REST API:
- A relatively new HTTP-based API.
- Language-independent and widely accessible.

2.2 Overview of REST API Authentication Methods

Flow Production Tracking (ShotGrid) REST API offers three authentication methods:

API Script Name/Key
User Name/Password
Session Token

Each has different intended use cases. API Script Name/Key is primarily for script or service automated access, while User Name/Password is for manual access by individual users. Session Token requires prior authentication through other methods, so we won't cover it in detail in this article.

2.3 ShotGrid's Proprietary Authentication System

Important: Flow Production Tracking (ShotGrid) REST API authentication uses a proprietary method that differs from standard OAuth 2.0 implementations. Pay special attention to the following points:

Legacy Login Requirement: Authentication requires a "Legacy Login" password set up in ShotGrid
Custom Authentication Endpoint: Instead of standard OAuth 2.0 endpoints, ShotGrid uses its own endpoint /api/v1.1/auth/access_token
Direct Authentication Method: The method directly sends username and password to the API, which is generally discouraged in OAuth 2.0 standards

ShotGrid authentication adopts a token-based system, but it's important to understand that it uses a proprietary implementation different from standard OAuth 2.0.

3. User Name/Password Authentication Details

3.1 Scenarios Requiring User Name/Password Authentication

Main scenarios where User Name/Password authentication is necessary:

When User-Specific Permissions Are Required:
- Data access based on individual user permissions
- Tracking activities by user
Client Application Development:
- Desktop tools, plugins, mobile apps, etc.
- Different settings or views per user
Environments Where API Script Authentication Can't Be Used:
- Site policies prohibit sharing script keys
- End users need to access with their own credentials

3.2 Pre-Configuration Steps

To use User Name/Password authentication, each user must follow these preliminary steps:

Creating a Personal Access Token (PAT) in Autodesk Account
- Log in to the Autodesk Account Profile Settings
- Go to Security > Personal Access Tokens and select Generate New Token
- For Token Scope, select Flow Production Tracking
- Enter a desired name in Token Name and select Generate Token
- Copy the generated Token (it cannot be displayed again, so be sure to save it)
Setting Up Personal Access Token in Flow Production Tracking (ShotGrid)
- Log in to SG admin screen (e.g., URL: https:///page/account_settings)
- Go to Account > Legacy Login and Personal Access Token
- Select Bind Token, enter a Token Name and paste the previously copied Token
- Select Bind
Setting Up Legacy Login in Flow Production Tracking (ShotGrid)
- Go to Account > Legacy Login and Personal Access Token
- Select Legacy Login and choose Enable Legacy Login
- Set a password using Change Password (Note that this password is used for User Name/Password authentication and differs from your Autodesk account password)

4. Authentication and Access with REST API

4.1 Authentication Flow Overview

The authentication flow for REST API can be summarized as:

First Access
- ✅ Authenticate with User Name/Password
- ✅ Get Access Token and Refresh Token
- ✅ Securely store Refresh Token
Regular API Usage
- ✅ Include Access Token in request header
- ✅ Process response
When Access Token Expires
- ✅ Use Refresh Token to obtain a new Access Token
- ✅ Retry request with the new Access Token
When Refresh Token Expires
- ✅ Re-authenticate with User Name/Password
- ✅ Get new Access Token and Refresh Token

Authentication Flow

4.2 Roles of Access Token and Refresh Token

There are two types of tokens, each with different roles:

Access Token: Used to access the REST API. Short expiration time (about 10 minutes)
Refresh Token: Used to obtain a new Access Token. Has a longer expiration time

Since Access Tokens expire quickly, they become invalid after a certain period. Therefore, you need to use the Refresh Token to obtain a new Access Token. When using a Refresh Token to obtain a new Access Token, login with User Name/Password is unnecessary, so it's essential to securely store the Refresh Token. From the user's perspective, this reduces the frequency of entering User Name/Password, improving convenience. In exchange, managing Refresh Tokens becomes mandatory.

4.3 Implementation Examples in Various Languages

4.3.1 Obtaining Access Token with User Name/Password

cURL

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=<username>&password=<password>" \
  https://<YourShotGridSite>/api/v1.1/auth/access_token

Python

import requests

auth_url = "https://<YourShotGridSite>/api/v1.1/auth/access_token"
payload = {
    "username": "<username>",
    "password": "<password>"  # ShotGrid's Legacy Login password
}

response = requests.post(auth_url, data=payload)
token_data = response.json()
access_token = token_data["access_token"]
refresh_token = token_data["refresh_token"]

JavaScript

async function getAccessToken() {
  const authUrl = 'https://<YourShotGridSite>/api/v1.1/auth/access_token';
  const formData = new URLSearchParams({
    username: '<username>',
    password: '<password>'  // ShotGrid's Legacy Login password
  });

  const response = await fetch(authUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: formData
  });

  const tokenData = await response.json();
  return {
    accessToken: tokenData.access_token,
    refreshToken: tokenData.refresh_token
  };
}

4.3.2 Accessing API with Access Token

cURL

# Example of retrieving project list using Access Token
curl -X GET -H "Authorization: Bearer <access_token>" \
  https://<YourShotGridSite>/api/v1.1/entity/project

Python

import requests

def get_projects(access_token):
    url = "https://<YourShotGridSite>/api/v1.1/entity/project"
    headers = {"Authorization": f"Bearer {access_token}"}
    response = requests.get(url, headers=headers)
    return response.json()

JavaScript

async function getProjects(accessToken) {
  const url = 'https://<YourShotGridSite>/api/v1.1/entity/project';
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  return await response.json();
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;

public async Task<dynamic> GetProjects(string accessToken)
{
    using (var client = new HttpClient())
    {
        client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Bearer", accessToken);
            
        var response = await client.GetAsync(
            "https://<YourShotGridSite>/api/v1.1/entity/project");
            
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<dynamic>(content);
    }
}

4.3.3 Obtaining New Access Token with Refresh Token

cURL

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=<refresh_token>" \
  https://<YourShotGridSite>/api/v1.1/auth/access_token

Python

def refresh_access_token(refresh_token):
    auth_url = "https://<YourShotGridSite>/api/v1.1/auth/access_token"
    payload = {
        "refresh_token": refresh_token
    }
    response = requests.post(auth_url, data=payload)
    token_data = response.json()
    return token_data["access_token"], token_data["refresh_token"]

JavaScript

async function refreshAccessToken(refreshToken) {
  const authUrl = 'https://<YourShotGridSite>/api/v1.1/auth/access_token';
  const formData = new URLSearchParams({
    refresh_token: refreshToken
  });

  const response = await fetch(authUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: formData
  });

  const tokenData = await response.json();
  return {
    accessToken: tokenData.access_token,
    refreshToken: tokenData.refresh_token
  };
}

5. Implementation Considerations

5.1 Essential Implementation Components

✅ User Authentication UI: Username/password input form
✅ Token Management:
- Secure storage of Access Token and Refresh Token
- Expiration check
- Auto-renewal functionality
✅ Error Handling:
- Token renewal logic for 401/403 errors
- User re-authentication prompt
✅ API Call Wrapper: Automatic authentication header addition

5.2 Timeline: Token Renewal Cycle

[Initial Authentication]──10 minutes──>[Token Expires]─(Use Refresh Token)─>[New Access Token]
                                         ↓
                                [Refresh Token Expires]
                                         ↓
                            [Request User Re-authentication]

5.3 Key Error Codes and Responses

Error Code	Meaning	Response
401 Unauthorized	Access token is invalid or expired	Get new token with Refresh Token; if that fails, re-authenticate
403 Forbidden	Insufficient permissions	Check user permissions or re-authenticate with an account having necessary permissions
429 Too Many Requests	API rate limit reached	Follow rate limits and retry with appropriate intervals
500 Server Error	Server-side error	Retry after a reasonable time or contact administrator

5.4 Response Format Example

Flow Production Tracking REST API responses are generally in JSON format. For example, when retrieving a project list:

{
  "data": [
    {
      "type": "Project",
      "id": 123,
      "attributes": {
        "name": "Project 1",
        "sg_status": "Active",
        "code": "PROJ1",
        "created_at": "2025-01-15T12:34:56Z"
      }
    },
    {
      "type": "Project",
      "id": 124,
      "attributes": {
        "name": "Project 2",
        "sg_status": "Active",
        "code": "PROJ2",
        "created_at": "2025-02-01T09:00:00Z"
      }
    }
  ]
}

Data is typically stored as an array within the data key, with each object containing type, id, and attributes.

6. Security Considerations

6.1 Secure Storage of Refresh Tokens

It's crucial to store Refresh Tokens securely. We recommend using OS keychains, password managers, or appropriate encryption.

Python

import keyring

# Store Refresh Token
# On Windows, it's stored in Credential Manager > Windows Credential
keyring.set_password("YourFlowProductionTrackingSiteRESTAPI", "RefreshToken", refresh_token)

JavaScript (Electron)

// Example of secure storage in an Electron app
const { safeStorage } = require('electron');
const fs = require('fs');

function saveToken(token) {
  const encryptedToken = safeStorage.encryptString(token);
  fs.writeFileSync('token.dat', encryptedToken);
}

function loadToken() {
  const encryptedToken = fs.readFileSync('token.dat');
  return safeStorage.decryptString(encryptedToken);
}

using System.Security.Cryptography;
using Microsoft.Win32;

public class TokenManager
{
    public static void SaveToken(string token)
    {
        // Encrypt data
        byte[] encryptedData = ProtectedData.Protect(
            System.Text.Encoding.UTF8.GetBytes(token),
            null, DataProtectionScope.CurrentUser);
            
        // Save to registry
        using (RegistryKey key = Registry.CurrentUser.CreateSubKey(@"SOFTWARE\YourApp"))
        {
            key.SetValue("RefreshToken", Convert.ToBase64String(encryptedData));
        }
    }
}

6.2 Other Authentication Considerations

Autodesk Identity (Autodesk Platform Services / formerly Forge) tokens cannot be used with ShotGrid. When researching Autodesk OAuth2 authentication, you might find , but this cannot be used for Flow Production Tracking (ShotGrid) authentication.
Pay attention to official documentation updates, as the Legacy Login method might change in the future.

7. Conclusion

This article provided detailed information about User Name/Password authentication for the Flow Production Tracking (ShotGrid) REST API. This authentication method uses a proprietary implementation different from common OAuth 2.0, and requires each user to set up Legacy Login beforehand.

When implementing, proper management of Access and Refresh Tokens is crucial. In particular, Refresh Tokens must be stored securely, and proper expiration handling and error processing should be implemented to use the API without compromising user experience.

For further learning, we recommend referring to the official Flow Production Tracking REST API documentation.

Authentication Guide for Flow Production Tracking (formerly known as ShotGrid) REST API

目次

1. Introduction

2. ShotGrid REST API Authentication Methods

2.1 Differences between API3 and REST API

2.2 Overview of REST API Authentication Methods

2.3 ShotGrid's Proprietary Authentication System

3. User Name/Password Authentication Details

3.1 Scenarios Requiring User Name/Password Authentication

3.2 Pre-Configuration Steps

4. Authentication and Access with REST API

4.1 Authentication Flow Overview

4.2 Roles of Access Token and Refresh Token

4.3 Implementation Examples in Various Languages

4.3.1 Obtaining Access Token with User Name/Password

4.3.2 Accessing API with Access Token

4.3.3 Obtaining New Access Token with Refresh Token

5. Implementation Considerations

5.1 Essential Implementation Components

5.2 Timeline: Token Renewal Cycle

5.3 Key Error Codes and Responses

5.4 Response Format Example

6. Security Considerations

6.1 Secure Storage of Refresh Tokens

6.2 Other Authentication Considerations

7. Conclusion