Roles and Permissions

Topsort utilizes a role-based access control (RBAC) approach to manage user permissions across dashboards. Roles are sets of permissions that can be assigned to users. Permissions define the specific actions a user can take within the Topsort platform. By assigning roles, you can efficiently manage user access across the two main interfaces: the Admin Dashboard for publishers/retailers and the Self-Service Dashboard for advertisers.

Key Concepts

• Roles: Collections of permissions that correspond to user functions (e.g., Admin, Sales).
• Permissions: Granular authorizations to perform specific actions on entities (e.g., create a campaign, view a report).
• Scopes: The domains or actions of the platform to which permissions apply (e.g., Campaigns, Reporting).
• Actions: The specific operations a user can perform on an entity within a scope (e.g., edit, read).

---

Admin Dashboard Roles

Two default roles are available for the Admin Dashboard:

1. Admin: This role grants full access to all features and settings within the publisher/retailer account. An Admin can manage campaigns, view all data analytics, manage users and their permissions, handle financial aspects, configure ad formats, set target ROAS, manage approval workflows and audiences, and access all reporting functionalities. This role is intended for key personnel who require complete control over the retail media network.
2. Sales: This role is designed for sales teams who manage relationships with specific advertisers. A user with the Sales role has full access to a designated group of advertisers. This includes creating and managing campaigns, viewing analytics, and generating reports only for the advertisers assigned to them. This ensures that sales representatives can effectively support their clients without having access to the entire advertiser portfolio.

Vendor Dashboard Roles

Two default roles are provided for the advertiser’s self-service environment:

1. Full Access: The Admin role for the advertiser’s dashboard provides full access to all functionalities within their own account. This includes managing campaigns, viewing detailed reporting and billing information, and adding or removing other users from their team.
2. Analytics: This role is ideal for users who need to monitor campaign performance and access data without the ability to make changes. A user with the Analytics role can view all reports and dashboards but cannot create or edit campaigns, manage users, or access billing information.

---

API Keys and Domains

API keys allow for programmatic access to the Topsort platform, enabling integrations with your existing systems. Each API key is scoped to a specific domain, ensuring that access is limited to the intended set of functionalities.

The following domains are available for API key creation, with each domain representing a group of related entities and actions:

• Catalog: Manage product catalogs, including adding, updating, and removing items.

• Auctions: Make ad requests.

• Events: Track user events and interactions.

• Campaigns / Assets / Webhooks: Create, manage, and monitor advertising campaigns, upload assets, and manage webhook configurations.

• Reporting: Access and export performance data and reports.

• Invitations / Users: Manage user accounts and invite new users.

• Segments: Create and manage audience segments.

• Billing: Access billing information, invoices, and payment history.

• Offsite: Manage offsite advertising campaigns.

• Toppie APIs: Interact with Topsort’s DSP.

• Toptimize APIs: Access and manage optimization features like quality scores, retrieval, and ranking.

• Forecasting: Utilize forecasting tools to predict campaign performance and inventory utilization.

  ---

  Custom Roles

  To provide more granular and tailored access, Topsort supports the creation of custom roles. This allows retailers to define specific permission sets that align perfectly with the unique responsibilities of their team members.

  How to Request a Custom Role

  The creation of new roles is a coordinated process between the retailer and the Topsort team. This ensures that permissions are configured correctly and securely.

  1. Define Your Needs: Identify the specific tasks and responsibilities the new role will have. Determine which domains (e.g., Campaigns, Reporting) the user needs to access and what actions (e.g., read, edit, etc.) they should be able to perform.
  2. Contact Your Topsort Account Manager: Reach out to your dedicated Topsort representative with the detailed requirements for the new role.
  3. Review and Implementation: The Topsort team will review the requested permissions and work with you to finalize the role’s scope.
  4. Deployment: Once confirmed, Topsort will configure the new role in your account. It will then appear in your Admin Dashboard’s user management section, ready to be assigned to users.

  Examples of Custom Roles

  Here are some examples of custom roles that can be created to meet specific organizational needs:

  Analytics

  • Purpose: Provide read-only access to the core data and reporting sections of the dashboard.
  • Example Scopes & Permissions:
    • Reporting: read
    • Campaigns / Assets / Webhooks: read
    • Users: No Access

  Finance Manager

  • Purpose: To manage and audit all financial aspects of the retail media network without having access to campaign or user management.
  • Example Scopes & Permissions:
    • Billing: read
    • Reporting: read
    • Campaigns / Assets / Webhooks: No Access
    • Users: No Access

  Merchandising Analyst

  • Purpose: To analyze product performance within ad campaigns and manage the product catalog for advertising eligibility, without being able to launch or edit campaigns.
  • Example Scopes & Permissions:
    • Catalog: read, edit (e.g., to tag items for ad eligibility)
    • Reporting: read
    • Segments: read
    • Campaigns / Assets / Webhooks: read (to view campaign settings without editing)

---

Object-Level Permissions (Access Control)

Beyond the broad definitions of roles, Topsort provides a more granular layer of security through instance-level permissions. The system combines Role-Based Access Control (RBAC) with instance-level control:

• Role: Defines the allowed actions (e.g., campaigns:read, campaigns:edit).
• Instance Permission: Defines the specific objects the action can be performed on (e.g., campaigns where advertiser_id = B).

This ensures that users and API keys only have access to the exact resources they are authorized for, enforcing the principle of least privilege.

How It Works

Policies are attached to a user or API key to filter their access down to specific instances of an entity. For example, the Sales role inherently uses this system to limit a user’s view to a specific group of advertisers. This can be extended to create highly specific access patterns.

Like custom roles, setting up these fine-grained policies is a coordinated process handled by the Topsort team to ensure proper and secure implementation.

Technical Examples

• User-to-Advertiser Access:
  • Scenario: A user jane.doe@retailer.com with a Sales role needs access to two specific advertisers: advertiser-123 and advertiser-456.
  • Policy: A policy is attached to Jane’s user account that restricts all her scopes (read, write, etc.) across all scopes (Campaigns, Reporting) to only those instances associated with the specified advertiser IDs. Any attempt to access data from advertiser-789 would be denied.

Config Files

Roles

{
  "roles": [
    {
      "name": "Admin",
      "dashboard": "admin",
      "description": "Provides unrestricted access to all features, settings, and data across the entire platform. Intended for key administrators.",
      "permissions": [
        {
          "scope": "*",
          "actions": [
            "read",
            "edit"
          ]
        }
      ]
    },
    {
      "name": "Sales",
      "dashboard": "admin",
      "description": "Provides full access to a specific list of advertisers. Requires an instance-level policy to define which advertisers the user can manage.",
      "instance_level_scoping": true,
      "permissions": [
        {
          "scope": "Campaigns",
          "actions": [
            "read",
            "edit"
          ]
        },
        {
          "scope": "Reporting",
          "actions": [
            "read",
            "edit"
          ]
        },
        {
          "scope": "Segments",
          "actions": [
            "read"
          ]
        },
        {
          "scope": "Billing",
          "actions": [
            "read"
          ]
        }
      ]
    },
    {
      "name": "Analytics",
      "dashboard": "admin",
      "description": "Provides read-only access to platform-wide data and reports. Cannot make any changes.",
      "permissions": [
        {
          "scope": "Reporting",
          "actions": [
            "read"
          ]
        },
        {
          "scope": "Campaigns",
          "actions": [
            "read"
          ]
        },
        {
          "scope": "Catalog",
          "actions": [
            "read"
          ]
        }
      ]
    },
    {
      "name": "AdvertiserAdmin",
      "dashboard": "advertiser",
      "description": "Provides full access within a single advertiser's account. This role is implicitly scoped to the advertiser they belong to.",
      "instance_level_scoping": true,
      "permissions": [
        {
          "scope": "Campaigns",
          "actions": [
            "read",
            "edit"
          ]
        },
        {
          "scope": "Reporting",
          "actions": [
            "read",
            "edit"
          ]
        },
        {
          "scope": "Billing",
          "actions":

Users

{
  "user_assignments": [
    {
      "email": "alice@retailer.com",
      "role": "Admin"
    },
    {
      "email": "bob@retailer.com",
      "role": "Sales",
      "advertisers": [
        "advertiser-id-123",
        "advertiser-id-456",
        "advertiser-id-789"
      ]
    },
    {
      "email": "carol@retailer.com",
      "role": "Analytics"
    },
    {
      "email": "dave@advertiser-brand.com",
      "role": "AdvertiserAdmin",
      "advertiser_id": "advertiser-id-123"
    },
    {
      "email": "eve@advertiser-brand.com",
      "role": "AdvertiserAnalytics",
      "advertiser_id": "advertiser-id-123"
    }
  ]
}