All Jobven API endpoints require authentication using an API key. This guide explains how to generate and use API keys securely.

Authentication Method

Jobven uses API Key authentication. Include your API key in the X-API-Key header with every request:

curl -X GET 'https://api.jobven.com/v1/public/jobs' \
  -H 'X-API-Key: your_api_key_here'

Generating API Keys

Step 1: Create an Account

If you haven't already, sign up for a Jobven account. You can start with the free tier.

Step 2: Navigate to API Keys

Once logged in, go to Dashboard → API Keys or visit jobven.com/dashboard/api-keys directly.

Step 3: Create a New Key

Click "Create API Key" and give it a descriptive name (e.g., "Production Server", "Development", "Analytics Pipeline").

Step 4: Copy Your Key

Using Your API Key

cURL

curl -X GET 'https://api.jobven.com/v1/public/jobs?limit=10' \
  -H 'X-API-Key: your_api_key_here'

JavaScript

const response = await fetch('https://api.jobven.com/v1/public/jobs?limit=10', {
  headers: {
    'X-API-Key': process.env.JOBVEN_API_KEY
  }
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://api.jobven.com/v1/public/jobs',
    headers={'X-API-Key': os.environ['JOBVEN_API_KEY']},
    params={'limit': 10}
)

data = response.json()

Security Best Practices

Example: Using Environment Variables

Node.js (.env file):

# .env
JOBVEN_API_KEY=your_api_key_here

// Load environment variables
require('dotenv').config();

// Use in your code
const apiKey = process.env.JOBVEN_API_KEY;

Python (.env file):

# .env
JOBVEN_API_KEY=your_api_key_here

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('JOBVEN_API_KEY')

Rate Limiting

Two limits apply, based on your subscription tier: a monthly allowance of jobs delivered, and a per-second cap on requests.

Limits by Tier

What counts as a job. Every job in a search response counts one, a single job lookup counts one, and every new or updated job delivered to a webhook endpoint counts one. Requests that return no jobs, company lookups, failed requests, and webhook closures and deletions are free. Company lookups stay available even after your allowance is spent; only the per-second limit applies to them. Page size does not change what you pay, so use the largest page your plan allows.

There is no daily cap. Your monthly allowance is yours to spend at whatever pace the per-second limit allows, so a single busy day can use as much of it as you like.

Rate Limit Headers

Every API response includes headers showing your current rate limit status:

X-RateLimit-Limit: 30000
X-RateLimit-Remaining: 28750
X-RateLimit-Reset: 1705392001

For per-request retry handling and the difference between burst limits and your monthly quota, see Handle Rate Limits.

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests error:

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please retry after 1 second.",
  "error": "Too Many Requests"
}

Best practices for handling rate limits:

1. Monitor headers — Check X-RateLimit-Remaining before making requests
2. Implement backoff — Use exponential backoff when you receive 429 errors
3. Spread requests — Distribute requests evenly instead of bursting
4. Cache responses — Cache data when possible to reduce API calls
5. Upgrade if needed — If you consistently hit limits, consider upgrading your tier

Retry with Exponential Backoff

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const body = await response.json().catch(() => ({}));
      // Burst limit responses include `retryAfter` (seconds); fall back to backoff
      const retryAfter = body.retryAfter ?? Math.pow(2, attempt);
      console.log(`Rate limited. Retrying after ${retryAfter}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Error Responses

401 Unauthorized

Returned when the API key is missing or invalid:

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

Common causes:

• Missing X-API-Key header
• Typo in the API key
• API key has been revoked
• Using the wrong API key (e.g., development key in production)

403 Forbidden

Returned when your API key doesn't have permission for the requested resource:

{
  "statusCode": 403,
  "message": "Insufficient permissions",
  "error": "Forbidden"
}

Managing API Keys

You can manage your API keys from the Dashboard → API Keys page:

• View usage — See how many calls each key has made
• Revoke keys — Immediately disable compromised keys
• Create new keys — Generate new keys for different environments
• Rename keys — Update key names for better organization

Next Steps

Now that you have an API key, you're ready to make your first API call: