GraphQL Schema Reference

Complete reference for AuditSwarm's GraphQL API.

---

Permissions

Queries

userPageAccess

Get all page access settings for a user.

query GetUserPageAccess($userId: String!) {
  userPageAccess(userId: $userId) {
    id
    pageName
    hasAccess
  }
}

Arguments:

• userId: String! - User ID to query

Returns: [PageAccess!]!

Example Response:

{
  "userPageAccess": [
    { "id": "pa_1", "pageName": "audits", "hasAccess": true },
    { "id": "pa_2", "pageName": "issues", "hasAccess": false },
    { "id": "pa_3", "pageName": "dashboards", "hasAccess": true }
  ]
}

Access Control: Admin only

---

userEntityPermissions

Get all entity-level permissions for a user.

query GetUserEntityPermissions($userId: String!) {
  userEntityPermissions(userId: $userId) {
    id
    entityType
    entityId
    permission
    isExplicit
  }
}

Arguments:

• userId: String! - User ID to query

Returns: [EntityPermission!]!

Types:

type EntityPermission {
  id: String!
  entityType: EntityType!
  entityId: String!
  permission: PermissionLevel!
  isExplicit: Boolean!
}

enum EntityType {
  AUDIT
  ISSUE
  RISK
  CONTROL
  WORKFLOW
  ARTIFACT
  DASHBOARD
}

enum PermissionLevel {
  view
  edit
}

Example Response:

{
  "userEntityPermissions": [
    {
      "id": "ep_1",
      "entityType": "AUDIT",
      "entityId": "audit_123",
      "permission": "edit",
      "isExplicit": true
    },
    {
      "id": "ep_2",
      "entityType": "WORKFLOW",
      "entityId": "wf_456",
      "permission": "view",
      "isExplicit": true
    }
  ]
}

Access Control: Admin only

---

Mutations

grantPageAccess

Grant a user access to a specific page.

mutation GrantPageAccess($input: GrantPageAccessInput!) {
  grantPageAccess(input: $input)
}

Input Type:

input GrantPageAccessInput {
  userId: String!
  pageName: String!  # 'audits', 'issues', 'risks', 'controls', 'dashboards', 'templates', 'time-keeping', 'admin'
}

Arguments:

• input: GrantPageAccessInput!
  • userId - User to grant access to
  • pageName - Page identifier (see list above)

Returns: Boolean! (true if successful)

Example:

mutation {
  grantPageAccess(input: {
    userId: "user_123"
    pageName: "audits"
  })
}

Access Control: Admin only

Side Effects:

• Creates or updates PageAccess record
• Logs action to AuditLog
• Invalidates user's permission cache

---

revokePageAccess

Revoke a user's access to a specific page.

mutation RevokePageAccess($userId: String!, $pageName: String!) {
  revokePageAccess(userId: $userId, pageName: $pageName)
}

Arguments:

• userId: String! - User to revoke access from
• pageName: String! - Page identifier

Returns: Boolean! (true if successful)

Example:

mutation {
  revokePageAccess(
    userId: "user_123"
    pageName: "admin"
  )
}

Access Control: Admin only

Side Effects:

• Deletes PageAccess record
• Logs action to AuditLog
• Invalidates user's permission cache

---

grantEntityPermission

Grant a user view or edit permission on a specific entity.

mutation GrantEntityPermission($input: GrantEntityPermissionInput!) {
  grantEntityPermission(input: $input) {
    id
    permission
  }
}

Input Type:

input GrantEntityPermissionInput {
  userId: String!
  entityType: EntityType!  # AUDIT, ISSUE, RISK, CONTROL, WORKFLOW, ARTIFACT, DASHBOARD
  entityId: String!
  permission: PermissionLevel!  # view, edit
}

Arguments:

• input: GrantEntityPermissionInput!
  • userId - User to grant permission to
  • entityType - Type of entity (enum)
  • entityId - Specific entity ID
  • permission - Level of access (view or edit)

Returns: EntityPermission!

Example:

mutation {
  grantEntityPermission(input: {
    userId: "user_123"
    entityType: AUDIT
    entityId: "audit_456"
    permission: edit
  }) {
    id
    permission
  }
}

Response:

{
  "grantEntityPermission": {
    "id": "ep_789",
    "permission": "edit"
  }
}

Access Control: Admin only

Side Effects:

• Creates or updates EntityPermission record
• Logs action to AuditLog
• Invalidates user's permission cache

Notes:

• Overwrites existing permission if already set
• Setting permission to "none" should use revokeEntityPermission instead

---

revokeEntityPermission

Revoke a user's permission on a specific entity (sets to "none" / explicit block).

mutation RevokeEntityPermission(
  $userId: String!
  $entityType: EntityType!
  $entityId: String!
) {
  revokeEntityPermission(
    userId: $userId
    entityType: $entityType
    entityId: $entityId
  )
}

Arguments:

• userId: String! - User to revoke permission from
• entityType: EntityType! - Type of entity
• entityId: String! - Specific entity ID

Returns: Boolean! (true if successful)

Example:

mutation {
  revokeEntityPermission(
    userId: "user_123"
    entityType: WORKFLOW
    entityId: "wf_789"
  )
}

Access Control: Admin only

Side Effects:

• Deletes EntityPermission record
• Logs action to AuditLog
• Invalidates user's permission cache

Behavior:

• After revocation, access depends on entity visibility:
  • Public entities: User can still view (unless explicitly blocked)
  • Private entities: User cannot access
• To explicitly block a public entity, grant permission with level "none" (not currently supported via GraphQL, use direct DB)

---

Users

Queries

users

Get all users (admins only).

query GetUsers {
  users {
    id
    email
    name
    image
    isAdmin
    createdAt
  }
}

Returns: [User!]!

Access Control: Admin only

---

Mutations

softDeleteUser

Soft delete a user (sets deletedAt timestamp).

mutation SoftDeleteUser($id: String!) {
  softDeleteUser(id: $id) {
    id
    email
    deletedAt
  }
}

Arguments:

• id: String! - User ID to delete

Returns: User!

Access Control: Admin only

Side Effects:

• Sets deletedAt timestamp
• User can no longer log in
• Permissions remain in database for audit trail
• Does NOT delete user data (GDPR compliance requires separate process)

Restrictions:

• Cannot delete admin users (must remove admin role first)
• Cannot delete yourself (current logged-in admin)

---

Common Patterns

Check If User Can Access Page

query CanAccessAuditsPage($userId: String!) {
  userPageAccess(userId: $userId) {
    pageName
    hasAccess
  }
}

Filter result:

const auditsAccess = data.userPageAccess.find(pa => pa.pageName === 'audits')
const canAccess = auditsAccess?.hasAccess ?? false

---

Check If User Can Edit Entity

query CanEditAudit($userId: String!) {
  userEntityPermissions(userId: $userId) {
    entityType
    entityId
    permission
  }
}

Filter result:

const perm = data.userEntityPermissions.find(
  ep => ep.entityType === 'AUDIT' && ep.entityId === 'audit_123'
)
const canEdit = perm?.permission === 'edit'

---

Grant Full Access to Audit and Workflows

mutation GrantFullAccess {
  # Step 1: Grant page access
  grantPageAccess(input: {
    userId: "user_123"
    pageName: "audits"
  })

  # Step 2: Grant edit on audit
  grantAuditPermission: grantEntityPermission(input: {
    userId: "user_123"
    entityType: AUDIT
    entityId: "audit_456"
    permission: edit
  }) {
    id
  }

  # Step 3: Grant edit on workflow
  grantWorkflowPermission: grantEntityPermission(input: {
    userId: "user_123"
    entityType: WORKFLOW
    entityId: "wf_789"
    permission: edit
  }) {
    id
  }
}

---

Remove All Access

mutation RemoveAllAccess {
  # Step 1: Revoke page access
  revokePageAccess(userId: "user_123", pageName: "audits")

  # Step 2: Revoke entity permissions
  revokeAuditPermission: revokeEntityPermission(
    userId: "user_123"
    entityType: AUDIT
    entityId: "audit_456"
  )

  revokeWorkflowPermission: revokeEntityPermission(
    userId: "user_123"
    entityType: WORKFLOW
    entityId: "wf_789"
  )
}

---

Error Handling

Common Errors

Insufficient Permissions

{
  "errors": [{
    "message": "Insufficient permissions to perform this action",
    "extensions": {
      "code": "FORBIDDEN",
      "requiredRole": "admin"
    }
  }]
}

Solution: Ensure user is authenticated as admin

---

User Not Found

{
  "errors": [{
    "message": "User not found",
    "extensions": {
      "code": "NOT_FOUND",
      "userId": "user_123"
    }
  }]
}

Solution: Verify user ID is correct

---

Cannot Delete Admin User

{
  "errors": [{
    "message": "Cannot delete admin users. Remove admin role first.",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Solution: Remove admin role before deletion

---

Related Documentation

• How to Manage Permissions
• Permission System Architecture
• Understanding Permissions