Skip to Content
Pindown.ai is in early alpha - features may change
API GuideCustom Roles & Permissions

Custom Roles & Pin Visibility

Control which users can see specific pins on shared pinboards using custom roles. This advanced RBAC feature allows you to create role-based access control for individual pins.

How It Works

  1. Create Custom Roles - Define roles like “VIP Members”, “Premium Users”, “Team Leads”
  2. Assign Roles to Users - Give specific collaborators one or more custom roles
  3. Set Pin Requirements - Mark pins as requiring specific roles to view
  4. Role-Based Visibility - Users only see pins they have permission to access

Use Cases

  • 🔐 VIP Content - Show premium pins only to VIP members
  • 👥 Team Sections - Different teams see different pins on the same board
  • 📊 Access Levels - Free vs. Paid tiers with different content
  • 🎯 Role-Based Dashboards - Executives, Managers, Staff see different views

Creating Custom Roles

Create up to 5 custom roles per pinboard. Each role has a name, color, and optional permissions.

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Create a "VIP Members" role
const vipRole = await client.pinboards.createRole('pb-abc123', {
  name: 'VIP Members',
  color: '#FFD700' // Gold color
})
 
console.log('Role created:', vipRole.roleId)
 
// Create more roles
const premiumRole = await client.pinboards.createRole('pb-abc123', {
  name: 'Premium Users',
  color: '#9333EA'
})
 
console.log('Premium role:', premiumRole.roleId)

Listing All Custom Roles

Get all custom roles for a pinboard:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// List all custom roles
const roles = await client.pinboards.listRoles('pb-abc123')
 
Object.entries(roles).forEach(([roleId, role]) => {
  console.log(`${roleId}: ${role.name} (${role.color})`)
})
 
// Output:
// role-xyz789: VIP Members (#FFD700)
// role-abc456: Premium Users (#9333EA)

Assigning Roles to Users

Assign custom roles to collaborators. Users must be invited to the pinboard first.

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// First, invite the user as a viewer or editor
await client.collaborators.inviteToPinboard('pb-abc123', {
  email: 'user@example.com',
  role: 'viewer' // Base role
})
 
// Then assign custom roles (after user accepts invite)
const userId = 'user-123'
await client.pinboards.assignUserRoles('pb-abc123', userId, [
  'role-xyz789',
  'role-abc456' // Assign multiple roles
])
 
console.log('User now has VIP Members + Premium Users roles')

Setting Pin Requirements

Mark specific pins as requiring custom roles. Only users with the assigned roles can see these pins.

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Make this pin visible only to VIP Members
await client.pinboards.setPinRoleRequirements('pb-abc123', 'p-pin1', [
  'role-xyz789' // Only VIP Members can see this
])
 
// Make another pin require multiple roles (user needs ALL roles)
await client.pinboards.setPinRoleRequirements('pb-abc123', 'p-pin2', [
  'role-xyz789',
  'role-abc456' // Requires BOTH roles
])
 
// Remove role requirements (make visible to all)
await client.pinboards.setPinRoleRequirements('pb-abc123', 'p-pin3', [])
 
console.log('Pin requirements updated')

Complete Example: VIP Section

Create a pinboard with VIP-only content:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: 'your_api_key'
})
 
async function setupVIPPinboard() {
  // 1. Create pinboard
  const pinboard = await client.pinboards.create({
    metadata: {
      title: 'Product Dashboard'
    }
  })
  
  const boardId = pinboard.id
  
  // 2. Create VIP role
  const role = await client.pinboards.createRole(boardId, {
    name: 'VIP Members',
    color: '#FFD700'
  })
  const roleId = role.roleId
  
  // 3. Create public pin (everyone can see)
  const publicPin = await client.pins.create({
    metadata: { title: 'Welcome to Dashboard' }
  })
  
  await client.pinboards.addPin(boardId, publicPin.pin_id)
  
  // 4. Create VIP pin (only VIP can see)
  const vipPin = await client.pins.create({
    metadata: { title: 'Exclusive VIP Content' }
  })
  
  await client.pinboards.addPin(boardId, vipPin.pin_id)
  
  // Set role requirement
  await client.pinboards.setPinRoleRequirements(boardId, vipPin.pin_id, [roleId])
  
  // 5. Invite regular user
  await client.collaborators.inviteToPinboard(boardId, {
    email: 'regular@example.com',
    role: 'viewer'
  })
  // Regular user only sees public pin
  
  // 6. Invite VIP user
  await client.collaborators.inviteToPinboard(boardId, {
    email: 'vip@example.com',
    role: 'viewer'
  })
  
  // Assign VIP role (after they accept invite)
  const vipUserId = 'user-vip123'
  await client.pinboards.assignUserRoles(boardId, vipUserId, [roleId])
  
  // VIP user sees BOTH public + VIP pins!
  
  console.log('✅ VIP Pinboard setup complete!')
  console.log('📌 Public pin visible to all viewers')
  console.log('💎 VIP pin visible only to VIP Members')
}
 
setupVIPPinboard()

Managing Roles

Update a Role

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Update a role
await client.pinboards.updateRole('pb-abc123', 'role-xyz789', {
  name: 'Premium VIP Members',
  color: '#FF6B00'
})
 
console.log('Role updated successfully')

Delete a Role

Deleting a role removes it from all users and pins automatically.

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Delete a role
await client.pinboards.deleteRole('pb-abc123', 'role-xyz789')
 
console.log('Role deleted successfully')
// All users lose this role
// All pins with this requirement become visible to all

Important Notes

  • Maximum 5 roles per pinboard
  • Owner always sees all pins regardless of role requirements
  • Users need ALL required roles to see a pin (AND logic, not OR)
  • Roles only work on pinboards, not individual pins
  • Users must be invited first before assigning custom roles
  • Deleting a role removes it from all users and pins automatically

Permission Matrix

User TypeCreate RolesAssign RolesView All PinsDelete Roles
Owner✅✅✅✅
Editor❌❌Only assigned roles❌
Viewer❌❌Only assigned roles❌

Next Steps

Sharing PinboardsOverview