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 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 have 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 to only 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.
API keys must have at least one role set.
var session = new ftrack.Session(
session = ftrack_api.Session(