Compliance & Events

Webex Teams is an end-to-end encrypted cloud collaboration platform. Organizations have exclusive control over the management of their encryption keys as well as the confidentiality of their data.

anchorOverview
anchor

Because we recognize that some data in Webex Teams may involve access to sensitive information about users and accounts, we built the Webex Teams Control Hub to support multiple types of administrator roles with access to different subsets of information. The Webex Control Hub provides a full-service management experience supporting trials, purchasing, account configuration, adoption, and customer support. For more information about the Webex Control Hub, please see this data sheet.

Within the Webex Control Hub, you can now associate administrative users with a new role to ensure that the data within Webex Teams remains in compliance with the legal standards in effect for an organization. This role is known as the Compliance Officer. Compliance officers will be able to use the Webex Teams API to access information within Webex Teams to aid in compliance activities for their organization.

Additionally, the Webex Teams API includes an Events API endpoint, which authorized third-party software can use to access, monitor, and archive the data created and shared by Webex Teams users within an organization.

This guide will provide more detail about the new Compliance Officer role, the Events API endpoint, and the types of permissions that can be used for data monitoring and management within Webex Teams. It will also describe the monitoring controls that can be put into place to ensure that all activities within Webex Teams are in full compliance with accepted business practices and internal standards.

anchorWebex Teams Data
anchor
Permissions & Ownership

Data that is created within Webex Teams is owned by the person, or organization, that created the room. Data access permissions within Webex Teams vary depending on a few factors: the room creator, room membership, and organization membership. When a room is created, the organization associated with the creator is considered the owning organization for the room. If users from other organizations are added to the room, those organizations are participating organizations in the room. Rooms created by bots are owned by the organization of the first non-bot participant.

In general, the following types of users will be viewing and creating data within Webex Teams:

  • Owning organization—can moderate and manage all data within rooms created by a member of the organization.
  • Room moderator—users can be assigned as a moderator by a room owner and have exclusive control of the room including the room’s title and participant list.
  • Room participants—can send and view messages within the room.
  • Compliance officers for the owning organization—can moderate or manage rooms as necessary to mitigate any issues that are not in compliance with the organization.
  • Compliance officers for the participating organization—can monitor data that has been created by their users only. They cannot monitor all data in the room if their organization is not the owning organization.

Note: The compliance officer for the organization that owns the room will be able to monitor all data created within that room. Whereas the compliance officer of a participating organization can only see their messages in a room which is owned by another organization.

Security & Privacy

A key management server (KMS) is responsible for the creation and security of the encryption keys the Webex Teams clients use to encrypt and decrypt data and communications. It is architecturally and operationally separated from the rest of the Webex Cloud and its data is not accessible by any other components. Whether the KMS is managed by Cisco or installed and managed on-premise, data within the Webex Cloud is encrypted from end-to-end and is not decrypted until it reaches the API endpoint.

For more information about data security and privacy in Webex Teams, please see the Webex Teams Security White Paper.

anchorCompliance
anchor
Compliance Officer

The role of a compliance officer is to ensure that a company is conducting its business in full compliance with all laws and regulations that pertain to its particular industry, as well as professional standards, accepted business practices, and internal standards.

The Webex Teams API has compliance authorization scopes that support the compliance officer’s role. Using these spark-compliance scopes, compliance officers will have access to and management of all data created by their organization including messages, content attachments, etc. in order to monitor data and to mitigate compliance issues that could arise.

Authorization Scopes

The spark-compliance scopes and their descriptions are listed below:

Scope
Usage
spark-compliance:events_read
Access to read events in your user's organization
spark-compliance:memberships_read
Access to read memberships in your user's organization
spark-compliance:memberships_write
Access to create/update/delete memberships in your user's organization
spark-compliance:messages_read
Access to read messages in your user's organization
spark-compliance:messages_write
Post and delete messages in all spaces in your user's organization
spark-compliance:rooms_read
Access to read rooms in your user's organization
spark-compliance:team_memberships_read
Access to read team memberships in your user's organization
spark-compliance:team_memberships_write
Access to update team memberships in your user's organization
spark-compliance:teams_read
Access to read teams in your user's organization

For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations/OAuth Guide.

Using the Compliance Scopes

Normally, Webex Teams API users only have access to information related to their account, such as messages in rooms where they are members. The spark-compliance scopes provide access to information across the organization. For instance, if granted the spark-compliance:messages_read scope, messages will be available for all rooms within the organization, not just those that the authenticated compliance officer is a member of.

Several scopes provide access to write data or take action within an organization. If an action should be taken against certain data within Webex Teams for compliance reasons, the Webex Teams API can be used with an authentication token authorized with one of the above scopes to carry out the action. For example, if a message needs to be deleted, the spark-compliance:messages_write scope will be required. To delete the message, use the DELETE /messages endpoint. Similarly, if a member of a room, either a person or a bot, needs to be removed, the spark-compliance:memberships_write scope will be required and the membership can be deleted with the DELETE /memberships endpoint. By using the appropriate spark-compliance: scopes and API endpoints, the authenticated user does not need to be a member of the room to take action.

anchorEvents
anchor
Introduction

The Events API endpoint gives developers access to events happening within their Webex Teams organization. Events can be integrated with Data Loss Prevention (DLP) software to check for policy violations and to take action to resolve any issues. The events available for monitoring include activities such as posting messages, sending content such as files, and group space membership changes. The Events API endpoint can be integrated with your existing archiving software to archive an unlimited amount of Webex Teams data. For access to events older than 90 days, the organization will need the Pro Pack for Webex Control Hub.

Use the Events API endpoint to access activities after they have occurred. Perhaps you need to retrieve every message sent by a particular user to comply with a legal discovery process, or you need to know which rooms someone joined and left. The Events API endpoint will give you access to this information quickly and securely.

Events are available for the following API resources whenever they are created, updated, or deleted:

Authorization Scopes

One scope for Events is available. Note that in order to use a spark-compliance scope you will need to be a designated compliance officer for your organization in the Webex Control Hub. For instructions on how to add these scopes to your app and for a full list of all available authorization scopes see the Integrations/OAuth Guide.

Scope
Usage
spark-compliance:events_read
Access to read events in your user's organization
Using Events

With the Events API endpoint you can retrieve information about user activities in Webex Teams such as message activity in spaces, content or files shared, or user membership changes in spaces.

The spark-compliance:events_read scope can be used by compliance officers to retrieve events for the entire organization.

When requesting a list of events from the API, the result may be split into pages. See the Pagination guide to learn how to navigate through paged API responses.

Example: Retrieve Created Messages

To retrieve all messages that have been created, use the List Events endpoint. Use URL query parameters to limit the response to include only events related to the messages resource and only created items by using: resource=messages&type=created.

GET https://api.ciscospark.com/v1/events?resource=messages&type=created

{
  "items" : [ {
    "id" : "Y2lzY29zcGFyazovL3VzL0VWRU5UL2JiY2ViMWFkLTQzZjEtM2I1OC05MTQ3LWYxNGJiMGM0ZDE1NAo",
    "resource" : "messages",
    "type" : "created",
    "actorId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "appId" : "null",
    "created" : "2015-10-18T14:26:16+00:00",
    "data" : {
      "id" : "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
      "roomId" : "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "roomType" : "group",
      "text" : "PROJECT UPDATE - A new project plan has been published on Box: http://box.com/s/lf5vj. The PM for this project is Mike C. and the Engineering Manager is Jane W.",
      "personId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
      "personEmail" : "matt@example.com",
      "created" : "2015-10-18T14:26:16+00:00"
    }
  } ]
}

In this example response, only one record is returned, but let's take a look at it in detail.

{
  "items" : [ {
    "id" : "Y2lzY29zcGFyazovL3VzL0VWRU5UL2JiY2ViMWFkLTQzZjEtM2I1OC05MTQ3LWYxNGJiMGM0ZDE1NAo",
    "resource" : "messages",
    "type" : "created",
    "actorId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "orgId" : "OTZhYmMyYWEtM2RjYy0xMWU1LWExNTItZmUzNDgxOWNkYzlh",
    "appId" : "null",
    "created" : "2015-10-18T14:26:16+00:00",
    "data" : {
      ... omitted ...
    }
  } ]
}

Each event object returned will contain several fields which describe the event. This includes:

  • id—a unique ID for the event
  • resource—which resource the event includes
  • type—the type of action which took place, such as created or deleted
  • actorId—the ID of the person which committed the activity for this event
  • orgId—the ID of the organization for the actor
  • appId—the ID of the integration or bot which committed the activity for this event
  • created—when the event took place
  • data—the data for the event
{
  "items" : [ {
    ... omitted ...
    "data" : {
      "id" : "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
      "roomId" : "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "roomType" : "group",
      "text" : "PROJECT UPDATE - A new project plan has been published on Box: http://box.com/s/lf5vj. The PM for this project is Mike C. and the Engineering Manager is Jane W.",
      "personId" : "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
      "personEmail" : "matt@example.com",
      "created" : "2015-10-18T14:26:16+00:00"
    }
  } ]
}

Inside of each event object, the data object will contain an object which represents the Webex Teams API resource at the time the event took place. For instance, in this event, a message object is returned to represent the message at the time of its creation.

For more information about how to use the Events API endpoint, please see the Events API Reference.

Last updated: November 8, 2018