Skip to Content
Pindown.ai is in early alpha - features may change
Pinboards APICustom Roles

Custom Roles API

Control pin visibility on shared pinboards using custom roles. Create role-based access control (RBAC) where only users with specific roles can see certain pins.

Overview

Custom roles enable advanced permission control:

  • Create up to 5 custom roles per pinboard
  • Assign multiple roles to each collaborator
  • Set role requirements on individual pins
  • Only users with required roles can see protected pins
  • Owner always sees all pins regardless of requirements

Create Custom Role

Create a new custom role for a pinboard:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Create custom role
const role = await client.pinboards.createRole('pb-abc123', {
  name: 'VIP Members',
  color: '#FFD700'
})
 
console.log('Role created:', role.roleId)

Request Body:

  • name (string, required) - Role name (e.g. “VIP Members”)
  • color (string, required) - Hex color code (e.g. “#FFD700”)
  • permissions (object, optional) - Future permission settings

Limits:

  • Maximum 5 roles per pinboard
  • Only owner can create roles

List 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})`)
})

Permissions:

  • Owner, Editors, Viewers can list roles
  • Required to see which roles exist before assigning

Update Custom Role

Update a role’s name or color:

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')

Permissions:

  • Only owner can update roles

Delete Custom Role

Delete a role and remove it from all users and pins:

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')
// Role is automatically removed from:
// - All users who had this role
// - All pins that required this role

Automatic Cleanup:

  • Removes role from all user assignments
  • Removes role from all pin requirements
  • If pin had only this role, it becomes visible to all

Permissions:

  • Only owner can delete roles

Assign Roles to User

Assign one or more custom roles to a collaborator:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// User must be invited first as editor or viewer
const userId = 'user-123'
 
// Assign custom roles to user
await client.pinboards.assignUserRoles('pb-abc123', userId, [
  'role-xyz789',
  'role-abc456'
])
 
console.log('User roles assigned successfully')
 
// To remove all roles, pass empty array:
// await client.pinboards.assignUserRoles('pb-abc123', userId, [])

Requirements:

  • User must already be a collaborator (editor or viewer)
  • Only owner can assign roles
  • Pass empty array [] to remove all roles

Set Pin Role Requirements

Control which roles are required to see a specific pin:

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// Require VIP role to see this pin
await client.pinboards.setPinRoleRequirements('pb-abc123', 'p-pin123', [
  'role-xyz789' // Only VIP Members can see
])
 
// Require MULTIPLE roles (user needs ALL)
await client.pinboards.setPinRoleRequirements('pb-abc123', 'p-pin456', [
  'role-xyz789',
  'role-abc456' // Needs BOTH roles
])
 
// Make pin visible to everyone
await client.pinboards.setPinRoleRequirements('pb-abc123', 'p-pin789', [])
 
console.log('Pin role requirements updated')

Logic:

  • Multiple roles = AND (user needs ALL specified roles)
  • Empty array = No restrictions (everyone can see)
  • Owner always sees all pins regardless of requirements

Permissions:

  • Only owner can set pin requirements

Complete Workflow Example

import { PindownClient } from '@pindownai/client-js'
 
const client = new PindownClient({
  apiKey: process.env.PINDOWN_API_KEY
})
 
// 1. Create pinboard
const board = await client.pinboards.create({
  title: 'VIP Dashboard'
})
const boardId = board.id
 
// 2. Create VIP role
const role = await client.pinboards.createRole(boardId, {
  name: 'VIP Members',
  color: '#FFD700'
})
const roleId = role.roleId
 
// 3. Create pins
const publicPin = await client.pins.create({ metadata: { title: 'Public Content' } })
const vipPin = await client.pins.create({ metadata: { title: 'VIP Only' } })
 
await client.pinboards.addPin(boardId, { pin_id: publicPin.id })
await client.pinboards.addPin(boardId, { pin_id: vipPin.id })
 
// 4. Protect VIP pin
await client.pinboards.setPinRoleRequirements(boardId, vipPin.id, [roleId])
 
// 5. Invite VIP user
await client.collaborators.inviteToPinboard(boardId, {
  email: 'vip@example.com',
  role: 'viewer'
})
 
// 6. Assign VIP role (after user accepts)
const vipUserId = 'user-vip123'
await client.pinboards.assignUserRoles(boardId, vipUserId, [roleId])
 
console.log('✅ VIP user can now see VIP-only pins!')

API Reference Summary

EndpointMethodDescriptionWho Can Access
/api/pinboards/:pbid/rolesPOSTCreate custom roleOwner
/api/pinboards/:pbid/rolesGETList all rolesOwner, Editors, Viewers
/api/pinboards/:pbid/roles/:roleIdPUTUpdate roleOwner
/api/pinboards/:pbid/roles/:roleIdDELETEDelete roleOwner
/api/pinboards/:pbid/users/:userId/custom-rolesPUTAssign roles to userOwner
/api/pinboards/:pbid/pins/:pinId/required-rolesPUTSet pin requirementsOwner

Important Notes

  • Maximum 5 roles per pinboard
  • Owner always sees all pins regardless of requirements
  • Multiple role requirements = AND logic (user needs ALL roles)
  • Users must be invited first before assigning custom roles
  • Deleting a role removes it from all users and pins automatically
  • Empty roleIds array removes all restrictions

See Also

Update LayoutBatch Get Pinboards