Authentication

Overview

The InstaView API uses API keys for authentication. Each API key is associated with a company and has specific scopes that control what actions it can perform.

API Key Format

InstaView API keys follow this format:

sk_1a2b3c4d5e6f7g8h9i0jklmnopqrstuv

Prefix: sk_ indicates a secret key
Key: Random Base62-encoded string (URL-safe, no special characters)
Length: Approximately 46 characters total

Never expose your API keys! Keep them secure and never commit them to version control. Use environment variables or secret management systems.

Authentication Method

Bearer Token

Pass your API key in the Authorization header with the Bearer scheme:

curl https://api.instaview.sk/jobs \
  -H "Authorization: Bearer sk_your_api_key_here"

This follows the industry-standard OAuth 2.0 Bearer token format for authentication.

Creating API Keys

Access your InstaView dashboard

Navigate to API Keys

Go to Settings → API Keys

Click Create Key

Click the Create API Key button

Configure the Key

Give it a descriptive name (e.g., “Production Integration”) - Select the required scopes - Optionally set an expiration date - Configure IP allowlist if needed

Save the Key

Copy the API key immediately - you won’t see it again!

Scopes and Permissions

API keys use scope-based access control. Each resource type has three permission levels:

Read

View and list resources

Write

Create and update resources

Delete

Delete resources (soft delete)

Available Scopes

Resource	Read Scope	Write Scope	Delete Scope
Jobs	`read:jobs`	`write:jobs`	`delete:jobs`
Candidates	`read:candidates`	`write:candidates`	`delete:candidates`
Interviews	`read:interviews`	`write:interviews`	-
Agents	`read:agents`	`write:agents`	`delete:agents`
Companies	`read:companies`	`write:companies`	-
Billing	`read:billing`	-	-

Scope Examples

Read Only
Full Access
Candidate Management

{
  "scopes": [
    "read:jobs",
    "read:candidates",
    "read:interviews"
  ]
}

Perfect for analytics dashboards and reporting tools.

{
  "scopes": [
    "read:jobs",
    "write:jobs",
    "delete:jobs",
    "read:candidates",
    "write:candidates",
    "delete:candidates",
    "read:interviews",
    "write:interviews",
    "read:agents",
    "write:agents",
    "delete:agents"
  ]
}

Complete access for primary integrations.

{
  "scopes": [
    "read:candidates",
    "write:candidates",
    "read:jobs",
    "read:interviews"
  ]
}

Focused access for candidate management systems.

Company Isolation

Every API key is scoped to a specific company. This ensures data isolation:

Keys can only access resources within their company
Cross-company access is prevented at the API level
Each company’s data is completely isolated

Regular API Keys

Standard API keys are associated with a single company:

# This key can only access resources for Company A
curl https://api.instaview.sk/jobs \
  -H "Authorization: Bearer sk_abc123def456ghi789jkl"

ATS Integration Keys

ATS (Applicant Tracking System) keys have special privileges:

Can create and manage multiple companies
Must specify companyId query parameter for resource access
Ideal for multi-tenant integrations

# ATS key accessing Company B's resources
curl https://api.instaview.sk/jobs?companyId=company-b-uuid \
  -H "Authorization: Bearer sk_ats123xyz456abc789def"

ATS keys can only be created by InstaView administrators. Contact support if you need ATS integration capabilities.

Security Best Practices

Use Environment Variables

Never hardcode API keys in your application code.

# .env file
INSTAVIEW_API_KEY=sk_your_key_here

// Node.js
const apiKey = process.env.INSTAVIEW_API_KEY;

Rotate Keys Regularly

Rotate API keys every 90 days - Create a new key before revoking the old one to avoid downtime - Use the dashboard to manage key lifecycle

Use Minimal Scopes

Apply the principle of least privilege: - Only grant scopes that are absolutely necessary - Use read-only keys for analytics and reporting - Create separate keys for different integrations

Configure IP Allowlists

Restrict API key usage to specific IP addresses:

{
  "allowedIPs": [
    "192.168.1.100",
    "10.0.0.0/8"
  ]
}

Keys will only work from these IP addresses.

Monitor Key Usage

Review API key audit logs regularly - Set up alerts for unusual activity - Track key usage in the dashboard

Set Expiration Dates

Configure automatic key expiration for temporary integrations:

Set expiration during key creation
Receive notifications before expiry
Ideal for contractor access or time-limited projects

Key Management

Listing Your Keys

View all API keys in your dashboard:

Active keys and their scopes
Last used timestamp
Creation date
Expiration date (if set)

Suspending Keys

Temporarily disable a key without deleting it:

// Keys can be suspended via the dashboard
// or programmatically through the admin API

Suspended keys will return a 401 Unauthorized error.

Revoking Keys

Permanently revoke a compromised key:

Revoked keys cannot be restored. Create a new key if needed.

Audit Logs

All API key operations are logged:

Key creation and deletion
Successful authentications
Failed authentication attempts
Scope changes
Suspension and revocation events

Common Authentication Errors

401 Unauthorized

error

Invalid or missing API key

{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}

Note: The API returns a generic error message to prevent information leakage about which keys are valid.

403 Forbidden

error

Insufficient scopes for the requested operation

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

This error occurs when your API key doesn’t have the required scope for the operation you’re trying to perform.

Rate Limiting: Rate limiting is planned for future implementation. Currently, the API does not enforce rate limits, but this feature will be added soon. When implemented, you’ll receive appropriate HTTP 429 responses with retry-after headers.

Next Steps

API Keys Guide

Deep dive into API key management

Scopes & Permissions

Learn about scope-based access control

Rate Limiting

Understand rate limits and best practices

Error Handling

Handle authentication errors properly

Getting Started

Core Concepts

Resources

Advanced

Overview

API Key Format

Authentication Method

Bearer Token

Creating API Keys

Scopes and Permissions

Read

Write

Delete

Available Scopes

Scope Examples

Company Isolation

Regular API Keys

ATS Integration Keys

Security Best Practices

Key Management

Listing Your Keys

Suspending Keys

Revoking Keys

Audit Logs

Common Authentication Errors

Next Steps

API Keys Guide

Scopes & Permissions

Rate Limiting

Error Handling

Getting Started

Core Concepts

Resources

Advanced

​Overview

​API Key Format

​Authentication Method

​Bearer Token

​Creating API Keys

​Scopes and Permissions

Read

Write

Delete

​Available Scopes

​Scope Examples

​Company Isolation

​Regular API Keys

​ATS Integration Keys

​Security Best Practices

​Key Management

​Listing Your Keys

​Suspending Keys

​Revoking Keys

​Audit Logs

​Common Authentication Errors

​Next Steps

API Keys Guide

Scopes & Permissions

Rate Limiting

Error Handling

Overview

API Key Format

Authentication Method

Bearer Token

Creating API Keys

Scopes and Permissions

Available Scopes

Scope Examples

Company Isolation

Regular API Keys

ATS Integration Keys

Security Best Practices

Key Management

Listing Your Keys

Suspending Keys

Revoking Keys

Audit Logs

Common Authentication Errors

Next Steps