Scopes and Permissions

Overview

InstaView uses scope-based permissions to provide granular access control. Each API key has a set of scopes that determine which operations it can perform on which resources.

Permission Model

Three-Level Access Control

Every resource type supports three permission levels:

Read

GET operations - List resources - View resource details - Search and filter

Write

POST and PATCH operations - Create resources - Update resources - Modify configurations

Delete

DELETE operations - Soft delete resources - Remove associations - Archive data

Scope Format

Scopes follow the format: <permission>:<resource>

read:jobs        // Can list and view jobs
write:contacts   // Can create and update contacts
delete:agents    // Can delete agents

Two names per scope

Conversation and contact scopes each answer to two names. InstaView’s API began in hiring, so its scopes were written in hiring nouns; agents now run sales, support and operations calls, where interview and candidate describe the wrong thing.

Current name	Legacy alias
`read:conversations`	`read:interviews`
`write:conversations`	`write:interviews`
`delete:conversations`	`delete:interviews`
`read:contacts`	`read:candidates`
`write:contacts`	`write:candidates`
`delete:contacts`	`delete:candidates`

They are the same permission. Holding either name satisfies a requirement for either, in both directions — a key with read:interviews reads /conversations, and a key with read:conversations reads /interviews.

There is nothing to migrate. Your existing key keeps the scopes it already has and keeps working, with no deadline attached. Keys created from now on are issued with the current names, and the dashboard offers only those. Every other scope family — jobs, agents, companies, billing, webhooks — is unchanged.

The tables below list the current name of each scope. Where a legacy alias exists it is named beside it, so you can recognise the scopes on a key you already have.

Available Scopes

Scope	Permissions	Operations
`read:jobs`	View jobs	`GET /jobs`, `GET /jobs/{id}`
`write:jobs`	Create/update jobs	`POST /jobs`, `PATCH /jobs/{id}`
`delete:jobs`	Delete jobs	`DELETE /jobs/{id}`

Common Combinations:

["read:jobs"]                              // Read-only
["read:jobs", "write:jobs"]                // Create and read
["read:jobs", "write:jobs", "delete:jobs"] // Full access

Scope	Legacy alias	Permissions	Operations
`read:contacts`	`read:candidates`	View contacts	`GET /contacts`, `GET /contacts/{id}`
`write:contacts`	`write:candidates`	Create/update	`POST /contacts`, `PATCH /contacts/{id}`
`delete:contacts`	`delete:candidates`	Delete contacts	`DELETE /contacts/{id}`

Contact fields ride on these scopes too, both halves of them: read:contacts reads the catalog (GET /contact-fields) and one contact’s values (GET /contacts/{id}); write:contacts defines, changes and removes fields (POST/PATCH/DELETE /contact-fields) and sets values (POST / PATCH /contacts), including ?createMissingFields=true.

There is no delete: requirement for removing a field definition. It removes schema, not a contact, and the values already stored deliberately survive it — requiring delete:contacts would imply the opposite.

Common Combinations:

["read:contacts", "read:jobs"]                   // View contacts and their jobs
["read:contacts", "write:contacts", "read:jobs"] // Manage contacts

Scope	Legacy alias	Permissions	Operations
`read:conversations`	`read:interviews`	View conversations	`GET /conversations`, `GET /conversations/{id}`
`write:conversations`	`write:interviews`	Schedule conversations	`POST /conversations`
`delete:conversations`	`delete:interviews`	Delete conversations	`DELETE /conversations/{id}`

Common Combinations:

["read:conversations"]                                                                                 // View results only
["read:conversations", "write:conversations", "read:contacts", "read:agents"]                           // Full conversation management
["read:conversations", "write:conversations", "delete:conversations", "read:contacts", "read:agents"]  // Full access

Scope	Permissions	Operations
`read:runs`	View a run and its conversations	`GET /runs/{id}`, `GET /runs/{id}/conversations`
`write:runs`	Create, attach, detach and drive the lifecycle	`POST /runs`, `POST /runs/{id}/contacts`, `DELETE /runs/{id}/contacts/{contactId}`, `POST /runs/{id}/launch`, `POST /runs/{id}/pause`, `POST /runs/{id}/resume`, `POST /runs/{id}/cancel`
`delete:runs`	Delete a run	`DELETE /runs/{id}`

New scopes, no legacy aliases, and nothing to migrate. Runs had no public surface before, so there is nothing to stay compatible with. Keys that already existed were granted all three, and new keys are issued with all three, so there is nothing for you to add.delete:runs exists for one operation and nothing else, so a key that may drive a run to completion need not also be able to remove it.Two operations need a second scope, because they reach data that is not the run: GET /runs/{id}/conversations needs read:conversations, and POST /runs/{id}/contacts needs read:contacts.Common Combinations:

["read:runs"]                                                  // Aggregate progress only
["read:runs", "read:conversations"]                            // Progress plus per-contact detail
["read:runs", "write:runs", "read:contacts"]                   // Build and drive runs
["read:runs", "write:runs", "delete:runs", "read:contacts"]    // Full access

Scope	Permissions	Operations
`read:agents`	View agents	`GET /agents`, `GET /agents/{id}`, `GET /agents/{id}/knowledge`
`write:agents`	Create/update	`POST /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/knowledge`, `POST /agents/{id}/knowledge/{documentId}/complete`, `PATCH /agents/{id}/knowledge/{documentId}`
`delete:agents`	Delete agents	`DELETE /agents/{id}`, `DELETE /agents/{id}/knowledge/{documentId}`

An agent’s knowledge base has no scopes of its own — it is part of the agent, so the scope you already hold for the agent covers its documents.Common Combinations:

["read:agents"]                   // View agent templates
["read:agents", "write:agents"]   // Manage agent configurations and knowledge bases

Scope	Permissions	Operations
`read:companies`	View company	`GET /companies/{id}`
`write:companies`	Update company	`PATCH /companies/{id}`
-	No delete	Companies cannot be deleted via API

Note: Regular API keys can only access their own company. ATS keys can access multiple companies.

Scope	Permissions	Operations
`read:billing`	View billing info	`GET /billing/usage`
-	No write	Billing changes must be made via dashboard
-	No delete	Billing data cannot be deleted

Read-only resource for monitoring usage and subscription status.

Scope	Permissions	Operations
`read:webhooks`	View webhooks	`GET /webhooks`, `GET /webhooks/{id}`
`write:webhooks`	Create/update webhooks	`POST /webhooks`, `PATCH /webhooks/{id}`, `DELETE /webhooks/{id}`, `POST /webhooks/{id}/test`, `POST /webhooks/{id}/reset-circuit`
-	No delete scope	Deletion uses `write:webhooks` scope

Common Combinations:

["read:webhooks"]                   // View webhook configurations
["read:webhooks", "write:webhooks"] // Full webhook management

Scope Validation

Request-Time Validation

Every API request validates the required scopes:

// Request
POST /jobs
Authorization: Bearer sk_xxx (scopes: ["read:jobs"])

// Response: 403 Forbidden
{
  "message": "Insufficient permissions: Required scope write:jobs not found",
  "error": "Forbidden",
  "statusCode": 403
}

Validation Flow

Extract API Key

API key is extracted from Authorization: Bearer header

Validate Key

Key is validated (not revoked, not expired, not suspended)

Check Scopes

Request’s required scope is compared against key’s scopes

Company Isolation

Verify resource belongs to key’s company (if applicable)

Execute Request

If all checks pass, request is processed

Scope Strategy

By Use Case

Analytics Dashboard
Contact Sync
Conversation Automation
Primary Integration
Webhook Handler

{
  "name": "Analytics Dashboard",
  "scopes": [
    "read:jobs",
    "read:contacts",
    "read:conversations",
    "read:billing"
  ]
}

Rationale: Dashboard only needs to view data, never modify it.

{
  "name": "ATS Contact Sync",
  "scopes": [
    "read:jobs",
    "read:contacts",
    "write:contacts"
  ]
}

Rationale: a sync tool creates and updates contacts and reads job info; it should not delete or modify jobs.

{
  "name": "Conversation Automation",
  "scopes": [
    "read:contacts",
    "read:agents",
    "read:conversations",
    "write:conversations"
  ]
}

Rationale: scheduling calls automatically needs read access to contacts and agents, and write access to create conversations.

{
  "name": "Primary Integration",
  "scopes": [
    "read:jobs",
    "write:jobs",
    "delete:jobs",
    "read:contacts",
    "write:contacts",
    "delete:contacts",
    "read:conversations",
    "write:conversations",
    "delete:conversations",
    "read:agents",
    "write:agents",
    "delete:agents",
    "read:companies",
    "write:companies",
    "read:billing",
    "read:webhooks",
    "write:webhooks"
  ]
}

Rationale: Main application integration needs full access to all resources.

{
  "name": "Webhook Configuration",
  "scopes": [
    "read:webhooks",
    "write:webhooks"
  ]
}

Rationale: Dedicated key for managing webhook configurations only.

Least Privilege Principle

Always grant the minimum scopes needed:

Why Least Privilege?

Reduces Attack Surface: Compromised keys have limited damage potential
Prevents Accidents: Applications can’t accidentally delete data they shouldn’t
Audit Trail: Scope requirements make it clear what each integration does
Compliance: Many regulations require least-privilege access

Example: Webhook Handler

A webhook handler that processes conversation completion events:❌ Too many scopes:

["read:conversations", "write:conversations", "read:contacts", "write:contacts"]

✅ Minimal scopes:

["read:conversations", "read:contacts"]

The webhook only needs to read conversations, not create or modify them.

Example: Reporting Tool

A reporting tool that generates analytics:❌ Includes write scopes:

["read:jobs", "write:jobs", "read:contacts", "write:contacts"]

✅ Read-only:

["read:jobs", "read:contacts", "read:conversations", "read:billing"]

Reporting tools should never have write or delete permissions.

Scope Dependencies

Some operations require multiple scopes due to resource relationships:

Creating a Contact

POST /contacts
{
  "jobId": "job-uuid",
  "firstName": "Jane",
  "lastName": "Doe"
}

Required Scopes:

write:contacts - To create the contact
read:jobs - To validate the job exists and belongs to your company

Creating a Conversation

POST /conversations
{
  "contactId": "contact-uuid",
  "agentId": "agent-uuid"
}

Required Scopes:

write:conversations - To create the conversation
read:contacts - To validate contact ownership
read:agents - To validate agent ownership

Listing Contacts with a Job Filter

GET /contacts?jobId=job-uuid

Required Scopes:

read:contacts - To list contacts
read:jobs - To filter by job

Cross-Resource Operations

Inline Resources

Some operations allow creating inline resources:

// Create a conversation with an inline contact
POST /conversations
{
  "contact": {
    "jobId": "job-uuid",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "gdprExpiryDate": "2026-11-16T12:00:00Z"
  },
  "agentId": "agent-uuid"
}

Required Scopes:

write:conversations - Primary operation
write:contacts - To create the inline contact
read:agents - To validate agent
read:jobs - To validate job

Inline resources (contact, job, agent) are created as part of the parent operation and need the same scopes as creating them directly. The XOR rule means you send either an existing id or an inline definition, never both.

Company Isolation

All scopes are enforced within company boundaries:

Regular API Keys

// Key belongs to Company A
Authorization: Bearer sk_abc123def456ghi789

// ✅ Can access Company A's jobs
GET /jobs

// ❌ Cannot access Company B's jobs (even if you know the ID)
GET /jobs/company-b-job-uuid
// Returns: 403 Forbidden

ATS Integration Keys

// ATS key with access to multiple companies
Authorization: Bearer sk_ats123xyz456abc789

// ✅ Must specify companyId for Company A
GET /jobs?companyId=company-a-uuid

// ✅ Can access Company B with different companyId
GET /jobs?companyId=company-b-uuid

// ❌ Cannot access Company C (not managed by this ATS key)
GET /jobs?companyId=company-c-uuid
// Returns: 403 Forbidden - "Access denied to this company"

Scope Errors

error

The API key lacks the required scope

{
  "message": "Insufficient permissions: Required scope write:jobs not found",
  "error": "Forbidden",
  "statusCode": 403
}

Solution: Add the required scope to your API key or create a new key with appropriate scopes.

error

Resource doesn’t exist or belongs to another company

{
  "message": "Access denied to this resource",
  "error": "Forbidden",
  "statusCode": 403
}

Causes:

Resource belongs to a different company
Resource has been soft-deleted
Invalid resource ID

Best Practices

Create Purpose-Specific Keys

Instead of one key with all scopes, create multiple keys for different purposes:

// Separate keys for different integrations
const analyticsKey = process.env.INSTAVIEW_ANALYTICS_KEY;    // read-only
const syncKey = process.env.INSTAVIEW_SYNC_KEY;              // write contacts
const automationKey = process.env.INSTAVIEW_AUTOMATION_KEY;  // write conversations

Document Required Scopes

Document which scopes each part of your application needs:

/**
 * Contact Sync Service
 *
 * Required Scopes:
 * - read:jobs (validate job ownership)
 * - read:contacts (check for duplicates)
 * - write:contacts (create/update contacts)
 */
class ContactSyncService {
  // ...
}

Handle Permission Errors

Gracefully handle insufficient permission errors:

async function createJob(jobData) {
  try {
    return await api.post('/jobs', jobData);
  } catch (error) {
    if (error.response?.status === 403) {
      console.error(
        `Permission denied: ${error.response.data.message}`
      );
      // Notify admin or fallback to alternative workflow
    }
    throw error;
  }
}

Regular Scope Audits

Periodically review API key scopes:

Are all scopes still necessary?
Can any keys be downgraded to read-only?
Are there unused keys that can be revoked?

Testing Scopes

Verify Your Scopes

// Verify your API key by making a simple GET request
// to any read endpoint you have access to, such as:
GET /jobs
Authorization: Bearer sk_abc123def456ghi789

// If successful, your API key is valid and has the required scope

Test Scope Requirements

// Test each operation with your key
const tests = [
  { method: "GET", path: "/jobs", scope: "read:jobs" },
  { method: "POST", path: "/jobs", scope: "write:jobs" },
  { method: "GET", path: "/contacts", scope: "read:contacts" },
  { method: "POST", path: "/contacts", scope: "write:contacts" },
];

for (const test of tests) {
  try {
    await api.request(test.method, test.path);
    console.log(`✅ ${test.scope}: Success`);
  } catch (error) {
    if (error.response?.status === 403) {
      console.log(`❌ ${test.scope}: Missing`);
    }
  }
}

Next Steps

API Keys

Learn about API key management

Rate Limiting

Understand rate limits per scope

Error Handling

Handle permission errors gracefully

Best Practices

Production integration patterns

Getting Started

Core Concepts

Resources

Advanced

Overview

Permission Model

Three-Level Access Control

Read

Write

Delete

Scope Format

Two names per scope

Available Scopes

Scope Validation

Request-Time Validation

Validation Flow

Scope Strategy

By Use Case

Least Privilege Principle

Scope Dependencies

Creating a Contact

Creating a Conversation

Listing Contacts with a Job Filter

Cross-Resource Operations

Inline Resources

Company Isolation

Regular API Keys

ATS Integration Keys

Scope Errors

Best Practices

Testing Scopes

Verify Your Scopes

Test Scope Requirements

Next Steps

API Keys

Rate Limiting

Error Handling

Best Practices

​Overview

​Permission Model

​Three-Level Access Control

Read

Write

Delete

​Scope Format

​Two names per scope

​Available Scopes

​Scope Validation

​Request-Time Validation

​Validation Flow

​Scope Strategy

​By Use Case

​Least Privilege Principle

​Scope Dependencies

​Creating a Contact

​Creating a Conversation

​Listing Contacts with a Job Filter

​Cross-Resource Operations

​Inline Resources

​Company Isolation

​Regular API Keys

​ATS Integration Keys

​Scope Errors

​Best Practices

​Testing Scopes

​Verify Your Scopes

​Test Scope Requirements

​Next Steps

API Keys

Rate Limiting

Error Handling

Best Practices

Overview

Permission Model

Three-Level Access Control

Scope Format

Two names per scope

Available Scopes

Scope Validation

Request-Time Validation

Validation Flow

Scope Strategy

By Use Case

Least Privilege Principle

Scope Dependencies

Creating a Contact

Creating a Conversation

Listing Contacts with a Job Filter

Cross-Resource Operations

Inline Resources

Company Isolation

Regular API Keys

ATS Integration Keys

Scope Errors

Best Practices

Testing Scopes

Verify Your Scopes

Test Scope Requirements

Next Steps