Frame.io API

Frame.io API Documentation

Welcome to Frame.io's official documentation portal.In here, you'll find everything you need to:

Get up and running with Frame.io's public API 🤙
Leverage powerful features like Webhooks and Custom Actions 🚀
Build your own OAuth2.0 app 🚢

Get Started    Guides

Manage Team Members and Collaborators

Use the Frame.io API to add users to your Teams and Projects.

Overview

This tutorial covers basic management of Users via the Frame.io API. It assumes the reader has already set up authentication via OAuth2.0 or with a Developer Token.

Core concepts

Leaving aside the specific nuances of different Team Member roles and permissions, there are two important keys to understand when managing Users via the Frame.io API:

  1. Team Members belong to Teams, and have access to all non-private Projects within those Teams. Team Managers and Admins are both extensions of the Team Member role.
  2. Project Collaborators belong to single Projects. Depending on how those Projects are configured, they may or may not be able to create Presentations, download Assets, or invite other Collaborators.

For more information, please refer to our Support documentation for Team Members vs. Collaborators, and Account Management Roles.

How Users join Accounts

👍

Don't worry about the details.

User join logic hinges on several pieces of information. If you're using the Frame.io API, you can ignore the vast majority of it.

In general, new Users are invited by current Users, either directly, or via unique Project join URL. Team Members may also:

  1. Add themselves to non-private Projects within public Teams in their Account
  2. Add themselves to public Teams within their Account
  3. Request to join private Teams within their Account

In all cases, join activities will go through a series of logical steps that include checking for prior tenancy, creating "pending" records, and dispatching invitation or join-request emails where appropriate.

The good news is, all of that logic is abstracted by the Frame.io API. If you want to add someone to a Project, use the Collaborator routes; if you want to invite someone to a Team, use the Team Member routes.

Required scopes

Scope

Reason

Teams: Update

Add and remove Team Members.

Projects: Update

Add and remove Project Collaborators.

Managing Team Members

Adding Team Members

To add a new Team Member to a Team, you'll need:

  1. The id of the target Team
  2. The email address of the target User.

From there, simply make an authorized POST to https://api.frame.io/v2/teams/:id/members, with the target User's email in the body payload like so:

{
    "email": "[email protected]"
}

If the User you've invited is already a Team Member in your organization, the API response will indicate as much:

{
    "_type": "team_member",
    "id": "<team-member-record-id>",
    "role": "member",
    "team_id": "<team-id>",
    "user_id": "<user-id>"
}

**If the User you've invited is not already in your organization, your request will trigger an invite flow, and the API response will look more like this:

{
    "_type": "pending_team_member",
    "email": "[email protected]",
    "id": "<oending-team-member-record-id>",
    "role": "member",
    "team_id": "<team-id>
}

Note: because the User isn't yet created or recognized, there won't be a mappable user_id in the pending_team_member response.

Removing Team Members

To remove a Team Member from a Team, you'll need:

  1. The id of the target Team
  2. The email address of the target User.

From here, you'll be making a DELETE call to the same URL as you would to add a Team Member, and passing it a special query string:

DELETE https://api.frame.io/v2/teams/:id/members/[email protected]

📘

Special abstraction alert

Note the /_?email= construction -- this is a special abstraction in the Frame.io API that enables you to manage your internal records fully off email addresses, without having to track our internal ID hierarchy.

On a successful call, the API will return a similar payload to Team Member addition. If the Team Member is being deleted for the first time, you'll see an updated_at attribute matching the time of your call. If the Team Member has been previously deleted, that timestamp will not update (i.e. it will reflect the time when the Team Member was initially removed).

{
    "_type": "team_member",
    "id": "<team-member-record-id>",
    "role": "member",
    "team_id": "<team-id>",
    "user_id": "<user-id>",
    "updated_at": "<timestamp>"
}

Attempts to remove Team Members who do not exist or were never associated with the Team will result in 404 errors.

📘

Under the hood

A Frame.io Team Member is a special join of a User, a Team, and a Role. Adding/removing Users to/from Teams actually creates a new record that the Frame.io backend manages separately from the User and Team.

The special /_? syntax used with the DELETE endpoint actually causes a sequence of lookups that results in deleting the special join record, without directly manipulating either the User, or the Team.

Managing Project Collaborators

Adding Project Collaborators

Collaborator management is extremely similar to Team Member management. To add a new Collaborator to a team, you'll need:

  1. The id of the target Project
  2. The email address of the target User.

From there, make an authorized POST to https://api.frame.io/v2/projects/:id/collaborators, with the target User's email in the body payload:

{
    "email": "[email protected]"
}

If the User you've invited is recognized and the Collaborator role can be instantiated instantly, the API response will indicate as much, and send back a full User object:

{
    "_type": "collaborator",
    "creator_id": "<inviting-user-id>",
    "id": "<collaborator-record-id>",
    "project_id": "<project-id>",
    "user": {
        "_type": "user",
       <...>
    },
    "user_id": "<user-id>"
}

👍

Remember: don't worry about the details.

If the User is already a Team Member in your organization, but is not a member of the target Project, you can still use the Collaborate route, and the API will respond as above. In the background, the Team Member will be added to your target Project, and will still be a Team Member.

In other words, you can't accidentally "demote" Team Members with this route.

If the User you've invited is new to your organization, your request will trigger an invite flow, and the API will respond with a pending_collaborator record, like so:

{
    "_type": "pending_collaborator",
    "email": "[email protected]",
    "id": "<pending-collaborator-record-id>",
    "project_id": "<project-id>"
}

Removing Project Collaborators

Note: this process is fundamentally identical to how Team Members are handled (above).

To remove a Collaborator from a Project, you'll need:

  1. The id of the target Project.
  2. The email address of the target User.

From here, you'll be making a DELETE call to the same URL as you would to add a Collaborator, and passing it a special query string.

DELETE https://api.frame.io/v2/projects/:id/collaborators/[email protected]

📘

Special abstraction alert

Note the /_?email= construction -- this is a special abstraction in the Frame.io API that enables you to manage your internal records fully off email addresses, without having to track our internal ID hierarchy.

On a successful call, the API will return a similar payload to Project Collaborator addition.:

{
    "_type": "collaborator",
    "creator_id": "<inviting-user-id>",
    "id": "<collaborator-record-id>",
    "project_id": "<project-id>",
    "user": {
        "_type": "user",
       <...>
    },
    "user_id": "<user-id>"
}

Attempts to remove Collaborators who do not exist or were never associated with the Project will result in 404 errors.

🚧

Collaborator removal is not idempotent

Unlike Team Member removal, attempts to remove already-removed Collaborators will also result in 404 errors.

Updated about a year ago

Manage Team Members and Collaborators


Use the Frame.io API to add users to your Teams and Projects.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.