Parsec
API docs by Redocly

Teams API (V1)

The Teams API provides a secure REST interface to Parsec for Teams resources. Using API keys created in the Parsec for Teams dashboard, external applications can manage team members, team computers, and guest access invites. This feature requires a subscription to an Enterprise plan.

Authentication

API keys are managed by the team owner in the Parsec for Teams dashboard. All API requests require authentication via bearer auth and must be made over HTTPS.

curl "https://api.parsec.app/v1/teams/1or58Uz1O6ObcpGCN9/guest-access-invites?offset=0&limit=50" \
  -H 'Authorization: Bearer tapi_1or58Uz1O6ObcpGCN9.YmM3ZDc1ZDM2ZTg2MGQ4MWQ4NWI2YTkw'

When team owners create API keys, they must explicitly grant the key access to the endpoints that they key will be used for. Each endpoint description in this document contains the permission that must be assigned to the API key in order to access the endpoint.

NOTE: It is critical to keep the API keys secret. Bad actors could use an API key to add themselves to the team and give themselves access to Team Computers.

Responses

Standard successful responses will have a data key which will be an object for the requested resource.

For requests with multiple resources, data is an array of paginated resources with count indicating total number of resources for the query. offset and limit query parameters can be used to paginate through the query results.

// single resource
{
  "data": {}
}

// paginated resources
{
  "data": []
  "count": 0
}

Errors

The API uses standard HTTP status codes to indicate success or failure of the request.

Status Code Description
200 OK
204 No Content
400 Bad Request
401 Unauthorized
404 Not Found
429 Too Many Requests
500 Internal Server Error

If the request status code is unsuccessful, additional details will be returned in a message key on the response body like following:

{
  "message": "Unauthorized"
}

Timestamps

Timestamps included in request body and responses are quoted strings in RFC 3339 format, with sub-second precision added if present.

Audit Log

Get Audit Log Events. Maximum 50 requests in 5 minute window. Blocked for 5 minutes if this quota is exceeded.

Get Team Events. The Access Audit Log permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
start_at
string <date-time>

Only include events that occurred on or after this date-time.

end_at
string <date-time>

Only include events that occurred at or before this date-time.

user_id
integer >= 1

Only include events with this user_id.

event_names
Array of strings unique

Only include events with these names (comma-separated).

limit
required
integer [ 1 .. 1000 ]

Limit the number of events returned.

cursor
string = 27 characters

ID of the first event to start paging from (inclusive). May not be supplied with after parameter. The value must be a valid KSUID.

after
string = 27 characters

ID of the first event to start paging from (exclusive). May not be supplied with cursor parameter. The value must be a valid KSUID.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next_cursor": "0ujssxh0cECutqzMgbtXSGnjorm"
}

Group

Get Team Groups

Get a paginated list of team groups. The View Groups permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
name
string

Search groups by name

offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Create Team Group

Create a team group. The Create Team Group permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
group_name
required
string [ 2 .. 64 ] characters

Name of the group.

allow_connections_within_group
required
boolean or null

Let members of this group connect with each other's workstations. This field is required.

Responses

Request samples

Content type
application/json
{
  • "group_name": "New York - Designers",
  • "allow_connections_within_group": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Team Group

Get a team group. The View Groups permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Team Group

Update a team group. The Update Team Group permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
group_name
string [ 2 .. 64 ] characters

Name of the group.

allow_connections_within_group
boolean or null

Let members of this group connect with each other's workstations.

Responses

Request samples

Content type
application/json
{
  • "group_name": "New York - Designers",
  • "allow_connections_within_group": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Team Group

Delete a team group. The Delete Team Group permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Responses

Remove Team Group Members

Remove members from the team group. The Remove Group Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
user_ids
required
Array of integers unique

List of members' user IDs

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Add Permitted Team Groups

Create connections with other groups. The Add Permitted Team Groups permission is required to access this endpoint.

  • Allow this group to accept incoming connections or to make outgoing connections
Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
group_ids
required
Array of integers non-empty unique

List of group IDs

direction
required
string
Enum: "incoming" "outgoing"

Define how this group's members connect with other groups on your team.

Responses

Request samples

Content type
application/json
{
  • "group_ids": [
    ],
  • "direction": "incoming"
}

Remove Permitted Team Groups

Remove connections with other groups. The Remove Permitted Team Groups permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
group_ids
required
Array of integers non-empty unique

List of group IDs

direction
required
string
Enum: "incoming" "outgoing"

Define which type of connections you want to remove.

Responses

Request samples

Content type
application/json
{
  • "group_ids": [
    ],
  • "direction": "incoming"
}

Add Team Group Members (Deprecated) Deprecated

Deprecated. Please use Assign Team Group Members instead.

Add members to the team group, removing any previously assigned groups. The Add Group Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
user_ids
required
Array of integers non-empty unique

List of member's user IDs

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Assign Team Group Members

Assign members to the team group. Any previously assigned groups remain. The Add Group Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
user_ids
required
Array of integers non-empty unique

List of member's user IDs

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Guest Access Invite

Get Guest Access Invite

Get a team guest access invite. The View Guest Access Links permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

Responses

Response samples

Content type
application/json
{}

Update Guest Access Invite

Update a guest access invite. The Manage Guest Access Links permission is required to access this endpoint.

  • Permission changes for keyboard, mouse, and gamepad are immediately pushed to connected guests.

  • Start/expiry updates can optionally use the send_email parameter to trigger Parsec to send an an update email to the guest.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

Request Body schema: application/json
host_peer_id
string

Peer ID of host machine

keyboard
boolean

Permission setting for controlling the keyboard

mouse
boolean

Permission setting for controlling the mouse

gamepad
boolean

Permission setting for using a gamepad

time_zone
string >= 3 characters

Time zone for starts_at and expires_at (IANA Time Zone database location names)

starts_at
string <date-time>

Timestamp of when guest access starts

expires_at
string <date-time>

Timestamp of when guest access ends

send_email
boolean

Flag for sending Parsec guest access email with updated event information (skipped if starts_at and expires_at did not change)

Responses

Request samples

Content type
application/json
{
  • "host_peer_id": "1pUe1weinVRfcejzWTq9srLpsTb",
  • "keyboard": false,
  • "mouse": false,
  • "gamepad": true,
  • "time_zone": "America/New_York",
  • "starts_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-26T14:15:22Z",
  • "send_email": false
}

Response samples

Content type
application/json
{}

Cancel Guest Access Invite

Cancel a guest access invite. The Manage Guest Access Links permission is required to access this endpoint.

  • If the guest access invite is unused, the guest access credit will be refunded to the team.

  • Guests connected to the host machine through the invite will be kicked out on cancellation.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

query Parameters
send_email
boolean

Flag for sending Parsec email notification to the guest informing them that the invite has been removed (defaults to false if not provided)

Responses

Get Guest Access Invites

Get a paginated list of guest access invites. The View Guest Access Links permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{}

Create Guest Access Invite

Create a guest access invite. The Create Guest Access Links permission is required to access this endpoint.

  • Creating a guest access invite will consume 1 guest access credit unless the guest is a member of the team.

  • starts_at must be scheduled in future.

  • expires_at must be scheduled after starts_at.

  • Use optional send_email parameter value to trigger Parsec to send a guest access invitation email.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
host_peer_id
required
string

Peer ID of host machine

guest_email
required
string <email>

Email of guest to be invited for access

event_name
required
string

Name of the guest access event

keyboard
required
boolean

Permission setting to control the keyboard

mouse
required
boolean

Permission setting to control the mouse

gamepad
required
boolean

Permission setting for using a gamepad

time_zone
required
string

Time zone for starts_at and expires_at (IANA Time Zone database location names)

starts_at
required
string <date-time>

Timestamp of when guest access starts

expires_at
required
string <date-time>

Timestamp of when guest access ends

message
required
string

Message to be included in guest access email

send_email
boolean

Flag for sending Parsec guest access email with link to join (defaults to false if not provided)

Responses

Request samples

Content type
application/json
{
  • "host_peer_id": "1pUe1weinVRfcejzWTq9srLpsTb",
  • "guest_email": "user@example.com",
  • "event_name": "Example event",
  • "keyboard": false,
  • "mouse": false,
  • "gamepad": true,
  • "time_zone": "America/New_York",
  • "starts_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "message": "You are invited to the Example event!",
  • "send_email": true
}

Response samples

Content type
application/json
{}

Kick Guest Access Guest

Force disconnect the guest from the guest access host machine. If guest is connected to host machine at the time of the request, they will get disconnected from host machine immediately.

If the guest access invite is still within valid window of start and expiry, the guest will be able to reconnect to the host machine again. To fully remove guest's access to host machine, the guest access invite should be deleted instead.

The Team Machine Kick Guest permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

Responses

Get Guest Access Invite Credits

Get a team's guest access invite credits balance. The View Credit Balance permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Responses

Response samples

Content type
application/json
{
  • "balance": 0
}

Machine

Get Team Machines

Get a paginated list of team machines. Various filters can be applied through query parameters to narrow the result down to specific subset of the team machines. The View Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

user_id
integer

Filter by machine's assigned team member user ID

team_group_id
integer

Filter by machine's assigned team group ID

name
string

Filter by machine's name

email
string <email>

Filter by machines' assigned member email

is_online
boolean

Filter by machine's online status

is_guest_access
boolean

Filter by machine's guest access status

assignment
string
Enum: "group" "unassigned" "member" "reservation"

Filter by machine's assignment

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 2
}

Update Team Machine

Update a team machine. The Manage Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Request Body schema: application/json
name
string

Name of machine

is_guest_access
boolean

Enable or disable guest access for machine

team_app_rule_id
string

App Rule ID to assign to the machine

Responses

Request samples

Content type
application/json
{
  • "name": "Example machine",
  • "is_guest_access": false,
  • "team_app_rule_id": "tar_27ntauS4uIvlrak78LJAUNLwjeM"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Team Machine

Delete a team machine. Existing session for the deleted team machine will be immediately invalidated. The Delete Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Responses

Get Team Machine

Get a team machine. The View Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

(Deprecated) Create Team Machine Assignment Deprecated

Deprecated. Please use Set Team Machine Assignment instead.

Assign a team machine to a team member or a team group. The Manage Team Computers permission is required to access this endpoint.

  • at least one request parameter is required for member user_id / email, or team_group_id.

  • team machine cannot be assigned to both member and group at once.

  • If email is provided and team member has not joined the team yet, a reservation will be created for the machine. Assignment will occur once team member with matching email joins the team.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Request Body schema: application/json
user_id
integer

User ID of team member

team_group_id
integer

ID of team group

email
string

Email of team member

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove Team Machine Assignment

Delete team machine assignment.

  • Team member, team group, and reservation assignments will be removed. The Manage Team Computers permission is required to access this endpoint.

  • Team machine will result in unassigned state.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Responses

Set Team Machine Assignment

Assign a team machine to a team member or team groups. The Manage Team Computers permission is required to access this endpoint.

  • at least one request parameter is required for member user_id / email, or team_group_ids.

  • team machine cannot be assigned to both member and group at once.

  • If email is provided and team member has not joined the team yet, a reservation will be created for the machine. Assignment will occur once team member with matching email joins the team.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Request Body schema: application/json
user_id
integer

User ID of team member

team_group_ids
Array of integers

ID of team group

email
string

Email of team member

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get App Rules

Get a paginated list of app rules. The View App Rules permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 2
}

Member

Get Team Members

Get a paginated list of team members. The View Team Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
group_id
integer

Search members by group ID

email
string

Search members by email

is_admin
boolean

Search admin members (default is unscoped)

offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Remove Team Member

Remove a team member from the team. The Remove Team Members permission is required to access this endpoint.

  • Team owner cannot be removed.

  • Members with API keys cannot be removed, you must first delete the API keys.

  • Team Computers assigned to the removed team member will be unassigned on removal.

  • SAML password reset email is optional through send_email query parameter for SAML enabled team members.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

userID
required
integer

ID of user

query Parameters
send_email
boolean
Deprecated

Flag for sending Parsec email for SAML password reset notification (defaults to false if not provided)

Responses

Get Team Member

Get a team member. The View Team Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

userID
required
integer

ID of user

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Member Invite

Get Team Invites

Get a paginated list of team member invites. The View Team Invites permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Create Team Invites

Create team member invites for the provided emails. Invites will expire one week from time of creation. Invited team members can join through the join_url provided in the response or through optional Parsec team invite emails sent with send_email flag. Only Parsec accounts with matching emails can use the join_url.

The Create Team Invites permission is required to access this endpoint.

SAML enabled teams should not use team invites, instead team members should be added through the SAML iDP.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ 1 .. 200 ] items unique [ items <email > ]

List of emails to be invited to join the team

group_id
integer

ID of the group to which team members should be added upon joining

team_app_rule_id
string

ID of the team app rule to which team members should be assigned upon joining. ID can be obtained through the admin dashboard.

send_email
boolean

Flag for sending Parsec team member email with link to join (defaults to false if not provided)

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "send_email": true
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Update Team Invites

Update team member invites for the provided emails. The Manage Team Invites permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ items <email > ]

Emails of users whose invites should be updated.

group_id
integer

ID of the group to which the invited users should be assigned.

team_app_rule_id
string

ID of the team app to which the invited users should be assigned.

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "group_id": 0,
  • "team_app_rule_id": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Cancel Team Invites

Cancel team member invites for the provided emails. The Delete Team Invites permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ items <email > ]

Emails of invites to be canceled.

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ]
}

Cancel Team Invites (Deprecated) Deprecated

Cancel team member invites. The Delete Team Invite permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ 1 .. 200 ] items unique [ items <email > ]

Emails of users to be invited to your team

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ]
}

Resend Team Invites

Resend existing team invites. This endpoint will extend the expiry of existing invites for an additional week from time of the request. Invited team members can join through join_url provided in the response or though optional Parsec team invite emails sent with send_email flag.

The Create Team Invites permission is required to access this endpoint.

SAML enabled teams cannot resend team invites.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ 1 .. 200 ] items unique [ items <email > ]
send_email
boolean

Flag for sending Parsec team member email with link to join (defaults to false if not provided)

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "send_email": true
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Team

Get Guest Access Invite

Get a team guest access invite. The View Guest Access Links permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

Responses

Response samples

Content type
application/json
{}

Update Guest Access Invite

Update a guest access invite. The Manage Guest Access Links permission is required to access this endpoint.

  • Permission changes for keyboard, mouse, and gamepad are immediately pushed to connected guests.

  • Start/expiry updates can optionally use the send_email parameter to trigger Parsec to send an an update email to the guest.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

Request Body schema: application/json
host_peer_id
string

Peer ID of host machine

keyboard
boolean

Permission setting for controlling the keyboard

mouse
boolean

Permission setting for controlling the mouse

gamepad
boolean

Permission setting for using a gamepad

time_zone
string >= 3 characters

Time zone for starts_at and expires_at (IANA Time Zone database location names)

starts_at
string <date-time>

Timestamp of when guest access starts

expires_at
string <date-time>

Timestamp of when guest access ends

send_email
boolean

Flag for sending Parsec guest access email with updated event information (skipped if starts_at and expires_at did not change)

Responses

Request samples

Content type
application/json
{
  • "host_peer_id": "1pUe1weinVRfcejzWTq9srLpsTb",
  • "keyboard": false,
  • "mouse": false,
  • "gamepad": true,
  • "time_zone": "America/New_York",
  • "starts_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-26T14:15:22Z",
  • "send_email": false
}

Response samples

Content type
application/json
{}

Cancel Guest Access Invite

Cancel a guest access invite. The Manage Guest Access Links permission is required to access this endpoint.

  • If the guest access invite is unused, the guest access credit will be refunded to the team.

  • Guests connected to the host machine through the invite will be kicked out on cancellation.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

query Parameters
send_email
boolean

Flag for sending Parsec email notification to the guest informing them that the invite has been removed (defaults to false if not provided)

Responses

Get Guest Access Invites

Get a paginated list of guest access invites. The View Guest Access Links permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{}

Create Guest Access Invite

Create a guest access invite. The Create Guest Access Links permission is required to access this endpoint.

  • Creating a guest access invite will consume 1 guest access credit unless the guest is a member of the team.

  • starts_at must be scheduled in future.

  • expires_at must be scheduled after starts_at.

  • Use optional send_email parameter value to trigger Parsec to send a guest access invitation email.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
host_peer_id
required
string

Peer ID of host machine

guest_email
required
string <email>

Email of guest to be invited for access

event_name
required
string

Name of the guest access event

keyboard
required
boolean

Permission setting to control the keyboard

mouse
required
boolean

Permission setting to control the mouse

gamepad
required
boolean

Permission setting for using a gamepad

time_zone
required
string

Time zone for starts_at and expires_at (IANA Time Zone database location names)

starts_at
required
string <date-time>

Timestamp of when guest access starts

expires_at
required
string <date-time>

Timestamp of when guest access ends

message
required
string

Message to be included in guest access email

send_email
boolean

Flag for sending Parsec guest access email with link to join (defaults to false if not provided)

Responses

Request samples

Content type
application/json
{
  • "host_peer_id": "1pUe1weinVRfcejzWTq9srLpsTb",
  • "guest_email": "user@example.com",
  • "event_name": "Example event",
  • "keyboard": false,
  • "mouse": false,
  • "gamepad": true,
  • "time_zone": "America/New_York",
  • "starts_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "message": "You are invited to the Example event!",
  • "send_email": true
}

Response samples

Content type
application/json
{}

Kick Guest Access Guest

Force disconnect the guest from the guest access host machine. If guest is connected to host machine at the time of the request, they will get disconnected from host machine immediately.

If the guest access invite is still within valid window of start and expiry, the guest will be able to reconnect to the host machine again. To fully remove guest's access to host machine, the guest access invite should be deleted instead.

The Team Machine Kick Guest permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

guestAccessInviteID
required
string

ID of guest access invite

Responses

Get Team Members

Get a paginated list of team members. The View Team Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
group_id
integer

Search members by group ID

email
string

Search members by email

is_admin
boolean

Search admin members (default is unscoped)

offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Remove Team Member

Remove a team member from the team. The Remove Team Members permission is required to access this endpoint.

  • Team owner cannot be removed.

  • Members with API keys cannot be removed, you must first delete the API keys.

  • Team Computers assigned to the removed team member will be unassigned on removal.

  • SAML password reset email is optional through send_email query parameter for SAML enabled team members.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

userID
required
integer

ID of user

query Parameters
send_email
boolean
Deprecated

Flag for sending Parsec email for SAML password reset notification (defaults to false if not provided)

Responses

Get Team Member

Get a team member. The View Team Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

userID
required
integer

ID of user

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Team Groups

Get a paginated list of team groups. The View Groups permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
name
string

Search groups by name

offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Create Team Group

Create a team group. The Create Team Group permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
group_name
required
string [ 2 .. 64 ] characters

Name of the group.

allow_connections_within_group
required
boolean or null

Let members of this group connect with each other's workstations. This field is required.

Responses

Request samples

Content type
application/json
{
  • "group_name": "New York - Designers",
  • "allow_connections_within_group": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Team Group

Get a team group. The View Groups permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Team Group

Update a team group. The Update Team Group permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
group_name
string [ 2 .. 64 ] characters

Name of the group.

allow_connections_within_group
boolean or null

Let members of this group connect with each other's workstations.

Responses

Request samples

Content type
application/json
{
  • "group_name": "New York - Designers",
  • "allow_connections_within_group": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Team Group

Delete a team group. The Delete Team Group permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Responses

Remove Team Group Members

Remove members from the team group. The Remove Group Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
user_ids
required
Array of integers unique

List of members' user IDs

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Add Permitted Team Groups

Create connections with other groups. The Add Permitted Team Groups permission is required to access this endpoint.

  • Allow this group to accept incoming connections or to make outgoing connections
Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
group_ids
required
Array of integers non-empty unique

List of group IDs

direction
required
string
Enum: "incoming" "outgoing"

Define how this group's members connect with other groups on your team.

Responses

Request samples

Content type
application/json
{
  • "group_ids": [
    ],
  • "direction": "incoming"
}

Remove Permitted Team Groups

Remove connections with other groups. The Remove Permitted Team Groups permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
group_ids
required
Array of integers non-empty unique

List of group IDs

direction
required
string
Enum: "incoming" "outgoing"

Define which type of connections you want to remove.

Responses

Request samples

Content type
application/json
{
  • "group_ids": [
    ],
  • "direction": "incoming"
}

Get Team Invites

Get a paginated list of team member invites. The View Team Invites permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Create Team Invites

Create team member invites for the provided emails. Invites will expire one week from time of creation. Invited team members can join through the join_url provided in the response or through optional Parsec team invite emails sent with send_email flag. Only Parsec accounts with matching emails can use the join_url.

The Create Team Invites permission is required to access this endpoint.

SAML enabled teams should not use team invites, instead team members should be added through the SAML iDP.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ 1 .. 200 ] items unique [ items <email > ]

List of emails to be invited to join the team

group_id
integer

ID of the group to which team members should be added upon joining

team_app_rule_id
string

ID of the team app rule to which team members should be assigned upon joining. ID can be obtained through the admin dashboard.

send_email
boolean

Flag for sending Parsec team member email with link to join (defaults to false if not provided)

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "send_email": true
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Update Team Invites

Update team member invites for the provided emails. The Manage Team Invites permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ items <email > ]

Emails of users whose invites should be updated.

group_id
integer

ID of the group to which the invited users should be assigned.

team_app_rule_id
string

ID of the team app to which the invited users should be assigned.

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "group_id": 0,
  • "team_app_rule_id": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Cancel Team Invites

Cancel team member invites for the provided emails. The Delete Team Invites permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ items <email > ]

Emails of invites to be canceled.

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ]
}

Add Team Group Members (Deprecated) Deprecated

Deprecated. Please use Assign Team Group Members instead.

Add members to the team group, removing any previously assigned groups. The Add Group Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
user_ids
required
Array of integers non-empty unique

List of member's user IDs

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Assign Team Group Members

Assign members to the team group. Any previously assigned groups remain. The Add Group Members permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

groupID
required
integer

ID of team group

Request Body schema: application/json
user_ids
required
Array of integers non-empty unique

List of member's user IDs

Responses

Request samples

Content type
application/json
{
  • "user_ids": [
    ]
}

Cancel Team Invites (Deprecated) Deprecated

Cancel team member invites. The Delete Team Invite permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ 1 .. 200 ] items unique [ items <email > ]

Emails of users to be invited to your team

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ]
}

Resend Team Invites

Resend existing team invites. This endpoint will extend the expiry of existing invites for an additional week from time of the request. Invited team members can join through join_url provided in the response or though optional Parsec team invite emails sent with send_email flag.

The Create Team Invites permission is required to access this endpoint.

SAML enabled teams cannot resend team invites.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

Request Body schema: application/json
emails
required
Array of strings <email> [ 1 .. 200 ] items unique [ items <email > ]
send_email
boolean

Flag for sending Parsec team member email with link to join (defaults to false if not provided)

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ],
  • "send_email": true
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 1
}

Get Team Machines

Get a paginated list of team machines. Various filters can be applied through query parameters to narrow the result down to specific subset of the team machines. The View Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

user_id
integer

Filter by machine's assigned team member user ID

team_group_id
integer

Filter by machine's assigned team group ID

name
string

Filter by machine's name

email
string <email>

Filter by machines' assigned member email

is_online
boolean

Filter by machine's online status

is_guest_access
boolean

Filter by machine's guest access status

assignment
string
Enum: "group" "unassigned" "member" "reservation"

Filter by machine's assignment

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 2
}

Update Team Machine

Update a team machine. The Manage Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Request Body schema: application/json
name
string

Name of machine

is_guest_access
boolean

Enable or disable guest access for machine

team_app_rule_id
string

App Rule ID to assign to the machine

Responses

Request samples

Content type
application/json
{
  • "name": "Example machine",
  • "is_guest_access": false,
  • "team_app_rule_id": "tar_27ntauS4uIvlrak78LJAUNLwjeM"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Team Machine

Delete a team machine. Existing session for the deleted team machine will be immediately invalidated. The Delete Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Responses

Get Team Machine

Get a team machine. The View Team Computers permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

(Deprecated) Create Team Machine Assignment Deprecated

Deprecated. Please use Set Team Machine Assignment instead.

Assign a team machine to a team member or a team group. The Manage Team Computers permission is required to access this endpoint.

  • at least one request parameter is required for member user_id / email, or team_group_id.

  • team machine cannot be assigned to both member and group at once.

  • If email is provided and team member has not joined the team yet, a reservation will be created for the machine. Assignment will occur once team member with matching email joins the team.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Request Body schema: application/json
user_id
integer

User ID of team member

team_group_id
integer

ID of team group

email
string

Email of team member

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Remove Team Machine Assignment

Delete team machine assignment.

  • Team member, team group, and reservation assignments will be removed. The Manage Team Computers permission is required to access this endpoint.

  • Team machine will result in unassigned state.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Responses

Set Team Machine Assignment

Assign a team machine to a team member or team groups. The Manage Team Computers permission is required to access this endpoint.

  • at least one request parameter is required for member user_id / email, or team_group_ids.

  • team machine cannot be assigned to both member and group at once.

  • If email is provided and team member has not joined the team yet, a reservation will be created for the machine. Assignment will occur once team member with matching email joins the team.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

machineID
required
string

ID of machine

Request Body schema: application/json
user_id
integer

User ID of team member

team_group_ids
Array of integers

ID of team group

email
string

Email of team member

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Audit Log Events. Maximum 50 requests in 5 minute window. Blocked for 5 minutes if this quota is exceeded.

Get Team Events. The Access Audit Log permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
start_at
string <date-time>

Only include events that occurred on or after this date-time.

end_at
string <date-time>

Only include events that occurred at or before this date-time.

user_id
integer >= 1

Only include events with this user_id.

event_names
Array of strings unique

Only include events with these names (comma-separated).

limit
required
integer [ 1 .. 1000 ]

Limit the number of events returned.

cursor
string = 27 characters

ID of the first event to start paging from (inclusive). May not be supplied with after parameter. The value must be a valid KSUID.

after
string = 27 characters

ID of the first event to start paging from (exclusive). May not be supplied with cursor parameter. The value must be a valid KSUID.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "next_cursor": "0ujssxh0cECutqzMgbtXSGnjorm"
}

Get App Rules

Get a paginated list of app rules. The View App Rules permission is required to access this endpoint.

Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

query Parameters
offset
required
integer >= 0

Number of results to skip before returning results

limit
required
integer [ 1 .. 200 ]

Number of results to return

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "count": 2
}

Un-assign App Rule from Members and Machines

Unassign the Team App Rule from team machines and members. The Manage App Rule Assignments permission is required to access this endpoint.

  • at least one request parameter is required: user_ids, or team_machine_ids.
Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

appRuleID
required
string

ID of the Team App Rule

Request Body schema: application/json
user_ids
Array of integers
team_machine_ids
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "user_ids": [
    ],
  • "team_machine_ids": [
    ]
}

Assign App Rule to Members and Machines

Assign the Team App Rule to team machines and members. The Manage App Rule Assignments permission is required to access this endpoint.

  • at least one request parameter is required: user_ids, or team_machine_ids.
Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

appRuleID
required
string

ID of the Team App Rule

Request Body schema: application/json
user_ids
Array of numbers
team_machine_ids
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "user_ids": [
    ],
  • "team_machine_ids": [
    ]
}

App Rule

Un-assign App Rule from Members and Machines

Unassign the Team App Rule from team machines and members. The Manage App Rule Assignments permission is required to access this endpoint.

  • at least one request parameter is required: user_ids, or team_machine_ids.
Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

appRuleID
required
string

ID of the Team App Rule

Request Body schema: application/json
user_ids
Array of integers
team_machine_ids
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "user_ids": [
    ],
  • "team_machine_ids": [
    ]
}

Assign App Rule to Members and Machines

Assign the Team App Rule to team machines and members. The Manage App Rule Assignments permission is required to access this endpoint.

  • at least one request parameter is required: user_ids, or team_machine_ids.
Authorizations:
Authorization
path Parameters
teamID
required
string

ID of team

appRuleID
required
string

ID of the Team App Rule

Request Body schema: application/json
user_ids
Array of numbers
team_machine_ids
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "user_ids": [
    ],
  • "team_machine_ids": [
    ]
}