Policies

Policies give organization administrators more control over the Integrations available for use within their organization. By default, any user can add an integration for use with Spark. To restrict the usage of integrations within an organization, create policies to define what is either allowed or disallowed by the organization.

Each policy contains an explicit action to either allow or deny access to external integrations. Policy options can specify which integrations, people, and/or authorization scopes it will apply to. These options may be combined to create very specific policies or omitted to cover a broader range of integrations.

Listing and viewing policies requires an administrator auth token with a scope of spark-admin:policies_read. Adding, updating, and removing policies requires an administrator auth token with the spark-admin:policies_write scope. To find out more about authorization scopes, see the scopes documentation.

Policy Options

  • Application — All integrations have a unique identifier, their appId. To determine the appId for a particular integration, please contact the developer of the integration.
  • People — Each person has a unique identifier, their personId. This ID can be found via the People API.
  • Scopes — Each integration is assigned one or more scopes, which define what it can do and what information within Spark it has access to. Policies can allow or disallow integrations by which particular scope or scopes they require. For a list of scopes integrations can use, please see the scopes documentation.
  • Name — The policy name is a free-form text field to help you describe each policy.

Policy Evaluation

Policies are evaluated from most to least specific, with an implicit allow if none apply. When no policies are present for an organization, all integrations are allowed.

When multiple policies match, the one with the latest (most recent) creation date will apply.

Examples

Limit Access to Certain People

To limit an integration to certain people, grant access to the permitted users and deny access to everyone else.

  1. Grant access to the integration to specific users:

    {
      "appId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "name": "Allow Integration 123",
      "personIds": [
        "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
        "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
        "Y2lzY29zcGFyazovL3VzL0NBTExTLzU0MUFFMzBFLUUyQzUtNERENi04NTM4LTgzOTRDODYzM0I3MQo"
      ],
      "scopes": [],
      "action": "allow"
    }
    
  2. Deny access to everyone else:

    {
      "appId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "name": "Deny Integration 123",
      "personIds": [],
      "scopes": [],
      "action": "deny"
    }
    

Grant Everyone Access to a Single Integration

To allow one integration and deny all others, create two policies, one to allow the specific integration (identified by the appId) and another policy to deny all other integrations (by omitting an appId). Because the second policy does not specify an appId, personId, or scope, it will act as a wildcard entry which will match all integrations.

  1. Grant access to the integration:

    {
      "appId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
      "name": "Allow Integration 123",
      "personIds": [],
      "scopes": [],
      "action": "allow"
    }
    
  2. Deny access to all integrations:

    {
      "appId": "",
      "name": "Deny All",
      "personIds": [],
      "scopes": [],
      "action": "deny"
    }
    

Method  
get https://api.ciscospark.com/v1/policies
post https://api.ciscospark.com/v1/policies
get https://api.ciscospark.com/v1/policies/{policyId}
put https://api.ciscospark.com/v1/policies/{policyId}
delete https://api.ciscospark.com/v1/policies/{policyId}