API keys are used to control access to resources through the API. There are two types of API keys in ftrack, personal and global.
API keys need to be used together with a username (api_user). See the example below. For personal API keys, the key must belong to the username, but for global API keys, the username could be any active user. When using a global key, permissions are assigned according to the role of the API key.
Personal API keys
Each user has a personal API key which has the same permissions as the user when logged into the ftrack web interface. The user API key can be found in My Account.
Global API keys
Typically, it makes sense to restrict specific API key permissions to just those required by specific scripts and/or users. This is possible by linking permission roles to API keys.
For example, it is possible to have an API key that can only perform read-only operations for general use, whilst a separate API key might have full write permissions.
The roles for API keys work the same as roles for users.
To add a new API role, navigate to System settings ‣ Security ‣ Roles. Click Create, enter a name for the role and select API in the Role type drop-down. Next, select the permissions you would like to include and click Save. For example, if you would like to restrict a role only to be able to create new projects, check the box next to Create and update projects and leave the rest as is.
To select a role for an API key, navigate to 'System settings' -> 'Security' -> 'API keys' and either create or edit an existing key. In the dialog that appears, select at least one role in the Roles drop-down to set or edit which role(s), and corresponding permissions, are applied for the key.
By default, a global API key can only access data in projects with private access turned off, also known as open projects.
A global API key will be able to access a private project if it is awarded access to the project. (You can do this in system settings by adding the project to the Projects attribute of the API key.)
Only private projects are visible in the ‘Projects’ drop-down of an API key’s edit dialog box because only private projects must be explicitly specified.
API keys must have at least one role set.
var session = new ftrack.Session(
session = ftrack_api.Session(