Permissions and roles (Authorization)

Available roles

Only a given subset of roles is available in Kitsu. Each of them has a fixed naming in the database but may be displayed in different ways in the Kitsu UI. You will find below the list of all the roles you can set on Kitsu users.

Role Definitions

Role	Code	Description	Typical Users
Admin	`admin`	Studio Manager	IT, Studio heads
Manager	`manager`	Production Manager	Producers, coordinators
Supervisor	`supervisor`	Department Lead	CG supervisors, leads
User	`user`	Artist	Modelers, animators, etc.
Client	`client`	External Reviewer	Clients, directors
Vendor	`vendor`	External Studio	Outsourcing partners

user, Artist - Artists can only access the productions they are part of. They can comment on tasks, upload media, and change statuses only on tasks that have been assigned to them. Their access is limited to a predefined set of statuses as determined by the Studio Manager.

Artist Permissions

They can:

Create personal filters on the global page and Task Type page.
Edit their own comments.
Check the checklist on their assigned tasks.
Create playlists-on-the-fly for shots or assets, but won't be able to save these playlists.

They cannot:

See client comments.
Access anything inside of projects that they haven't been assigned to.

supervisor, Supervisor - Department supervisors inherit Artist permissions. Department supervisors have read and write access to their department(s) they work on: assets, shots, tasks, assignments, statistics, breakdown, and playlists.

Supervisor Permissions

They can:

Assign tasks to their team artists (same department).
Post comments on all tasks or their department(s).
Check a checklist in their own department.
Pin a comment.
Edit their own comments.
Add/edit a playlist for the studio or the client.
See client comments and validations.
See comments from other departments.
View the timesheets of their team department(s).

They cannot:

Access the studio team, the main timesheets, and the production list
Define task types, task statuses, and asset types.
Comment on other departments than theirs; they can't assign artists from other departments.

manager, Production Manager - Production managers inherit Department supervisor permissions. Production managers have read and write access to the productions they are assigned to, including assets, shots, tasks, assignments, statistics, breakdowns, and playlists.

Production Manager Permissions

They can:

Create assets and shots, either manually or through a CSV batch import.
Post comments on any tasks within the production.
Edit any comment within the production.
Check any checklist within the production.
Pin any comment within the production.
Add a task column.
Delete or add a task.
Add/edit a playlist for the studio or the client.
See client comments and validations.

They cannot:

Access the studio page, the main timesheets, and the production list.
Define task types, task statuses, and asset types.

admin, Studio Manager - A Studio Manager acts in the same way as an Administrator, having read and write access to all productions and settings within Kitsu.

Studio Manager / Administrator Permissions

They can:

Create and edit a production
Manage the studio
Define the permission role of each user.

Customize global aspects of Kitsu like adding and modifying task types, task statuses, and asset types.
Set permission roles
Customize high-level studio information like customizing the studio name adding the company logo, and defining the number of hours per day of work etc.
Choose to use the original filename for downloading media.
They have full access to all productions on your Kitsu site.
They have the same permissions as the supervisor.
They can add / delete a task column.
They are allowed to create custom metadata columns.

vendor, Vendor - Vendors have similar permissions to artists, except they can only see and edit tasks they are specifically assigned to.

client, Client - Clients can only see the productions they are part of.

Clients Permissions

They can:

Access the global page of the assets/shots.
Access the stats pages.
Access Client playlists with limited access to task status when they post a comment

Note

Only Supervisors and the Studio Manager can see the Client retake or validation status.

They cannot:

See task assignments
See comments that they didn't write

Change a role

It's currently not possible to define a new role when creating or editing persons.

You can only assign one of user, admin, manager, supervisor, vendor, or client.

PythoncURL

python

person = gazu.person.new_person(
    first_name="hello",
    last_name="world",
    email="test@cg-wire.com",
    phone="",
    role="user"
)

person['role'] = 'manager'

gazu.person.update_person(person)

bash

curl -X POST "http://api.example.com/data/persons" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "password": "securepassword123",
    "role": "user",
    "active": true,
    "contract_type": "permanent",
    "two_factor_authentication": "none",
    "expiration_date": "2025-12-31",
    "is_bot": false
  }'

curl -X PUT "http://api.example.com/data/persons/a24a6ea4-ce75-4665-a070-57453082c25" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "password": "newsecurepassword123",
    "role": "manager",
    "active": true,
    "contract_type": "freelance",
    "two_factor_authentication": "totp",
    "expiration_date": "2025-12-31"
  }'

Per-project roles

A person has one global role, but can be given a different role on a specific production: someone working as an artist on most projects can act as a supervisor on one of them. The project role only applies inside that production; the global role keeps applying everywhere else.

Set the role when adding the person to the team, or change it later:

PythoncURL

python

gazu.project.add_person_to_team(project, person, role="supervisor")

gazu.project.update_team_member_role(project, person, "manager")

# Back to the global role
gazu.project.update_team_member_role(project, person, None)

bash

curl -X PUT "http://api.example.com/data/projects/a24a6ea4-ce75-4665-a070-57453082c25/team/b35b7fb5-df86-5776-b181-68564193d36" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "supervisor"}'

Rules to know:

Assignable project roles: user, supervisor, manager, client and vendor. admin stays a global-only role and is rejected with a 400.
A person without an explicit project role inherits their global role, and keeps following it when the global role changes later.
Changing a project role requires manager rights on that project: a per-project manager can manage the roles of their own production.
The team listing exposes the explicit role of each member under the project_role key (None means the global role applies). The update response returns the same value under a role key.

Preview accounts

A production manager can create a read-only client account for the production, to check what a client sees before sharing a page. It is a verification tool, not a way to give clients free access. Routes, all restricted to the managers of the production and to admins:

Method	Route	Result
`GET`	`/data/projects/<project_id>/preview-account`	The account, or `null` when there is none (200)
`POST`	`/data/projects/<project_id>/preview-account`	Creates the account, or regenerates its password (201)
`PUT`	`/data/projects/<project_id>/preview-account`	Opens or blocks the account (200)
`DELETE`	`/data/projects/<project_id>/preview-account`	Deletes the account (204, also when there is none)

bash

# Create (or regenerate the password)
curl -X POST "http://api.example.com/data/projects/a24a6ea4-ce75-4665-a070-57453082c25/preview-account" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Open for one hour
curl -X PUT "http://api.example.com/data/projects/a24a6ea4-ce75-4665-a070-57453082c25/preview-account" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_open": true}'

The account dict has the keys id, email, full_name and preview_open_until (UTC ISO date, or null when blocked). The POST response adds the clear password: it is returned only once.

Rules to know:

Only available with local classic authentication. The routes return 400 otherwise. Read the preview_accounts_enabled key of GET /config to know if the feature is available.
A new account is blocked. PUT with {"is_open": true} opens it for one hour, and extends the window when it is already open. {"is_open": false} blocks it immediately. PUT returns 404 when the production has no account.
Blocking, reopening after a block or an expiry, and regenerating the password end the existing sessions of the account. Extending an open window keeps them.
The account is read-only: any write returns 403.
It does not count as a seat, is hidden from GET /data/persons, cannot be assigned to a task or mentioned. Its id still appears in the team of the production.
It is deleted with its production.
On the preview account, GET /auth/authenticated returns a non-null preview_project_id.

Check a person's role

PythoncURL

python

person = gazu.person.get_person(id=user['user']['id'], relations=True)

role = person['role']

if role == "admin":
    ...

bash

curl "http://api.example.com/data/persons/a24a6ea4-ce75-4665-a070-57453082c25?relations=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Check a user belongs to a studio

One person can only belong to a single studio.

Python

python

person = gazu.person.get_person(id=user['user']['id'], relations=True)

studio = gazu.studio.get_studio_by_name('Sydney')

if studio['id'] == person['studio_id']:
    ...

Check a person belongs to a department

One person can belong to many departments.

Python

python

person = gazu.person.get_person(id=user['user']['id'], relations=True)

department = gazu.person.get_department_by_name('Animation')
departments = person['departments']

if department['id'] in departments:
    ...

DCC

Messaging

Gazu Python SDK

Permissions and roles (Authorization)

Available roles

Role Definitions

Change a role

Per-project roles

Preview accounts

Check a person's role

Check a user belongs to a studio

Check a person belongs to a department

Gazu Python SDK

Permissions and roles (Authorization) ​

Available roles ​

Role Definitions ​

Change a role ​

Per-project roles ​

Preview accounts ​

Check a person's role ​

Check a user belongs to a studio ​

Check a person belongs to a department ​

Permissions and roles (Authorization)

Available roles

Role Definitions

Change a role

Per-project roles

Preview accounts

Check a person's role

Check a user belongs to a studio

Check a person belongs to a department