Skip to main content

Authentication

The JsonCut API uses API key authentication to secure access to your account and resources. All API requests must include a valid API key.

Getting Your API Key​

  1. Sign up for an account at app.jsoncut.com
  2. Navigate to the API Keys section in your dashboard
  3. Click "Generate New API Key"
  4. Copy and securely store your API key
Keep Your API Key Secure

Your API key provides access to your account and should be treated like a password:

  • Never expose it in client-side code
  • Don't commit it to version control
  • Use environment variables in production
  • Rotate keys regularly for security

Using Your API Key​

Include your API key in the x-api-key header of every request:

curl -H "x-api-key: YOUR_API_KEY_HERE" \
     https://api.jsoncut.com/v1/files

Authentication Examples​

cURL​

curl -X GET \
  -H "x-api-key: jc_live_abc123def456..." \
  -H "Content-Type: application/json" \
  https://api.jsoncut.com/v1/files

JavaScript (Node.js)​

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.jsoncut.com/v1',
  headers: {
    'x-api-key': 'jc_live_abc123def456...',
    'Content-Type': 'application/json'
  }
});

// Use the client for requests
const response = await client.get('/files');

Python​

import requests

headers = {
    'x-api-key': 'jc_live_abc123def456...',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.jsoncut.com/v1/files',
    headers=headers
)

Testing Your Authentication​

Verify your API key is working with a simple request:

curl -H "x-api-key: YOUR_API_KEY" \
     https://api.jsoncut.com/v1/files

Successful response:

{
  "files": [],
  "total": 0,
  "page": 1,
  "per_page": 20
}

Authentication error:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Key Rotation​

Regularly rotate your API keys for security:

  1. Generate a new API key in the dashboard
  2. Update your applications with the new key
  3. Test that everything works correctly
  4. Delete the old API key

Multiple Keys​

Consider using different API keys for different environments or applications:

This allows you to:

  • Track usage by environment
  • Revoke access to specific applications
  • Maintain separation of concerns

API Key Permission System​

JsonCut uses a simple two-level permission system for API keys. When creating an API key in the dashboard, you can choose between two permission levels:

Available Permission Levels​

Read-Only Access:

  • Can view and download files
  • Can view job details and status
  • Cannot create, modify, or delete anything
  • Perfect for monitoring, analytics, and display applications

Full Access:

  • Can perform all operations
  • Upload, modify, and delete files
  • Create, cancel, and manage jobs
  • Full API access for production applications

Creating API Keys​

Creating API keys is simple through the dashboard:

  1. Navigate to API Keys section in your dashboard
  2. Click "Create New API Key"
  3. Enter a descriptive name for your key
  4. Choose permission level: Read-Only or Full Access
  5. Optionally set an expiration date
  6. Click "Create Key"
  7. Copy and securely store your new API key
Security Best Practice

Use Read-Only keys whenever possible for applications that don't need to modify data. This reduces security risks if a key is compromised.

Managing API Keys​

  • View Keys: See all your API keys and their permissions in the dashboard
  • Monitor Usage: Check usage statistics for each key
  • Rotate Keys: Create new keys and delete old ones for security
  • Revoke Access: Delete API keys that are no longer needed

Next Steps​

Now that you understand authentication and permissions, you're ready to:

Troubleshooting​

Common Authentication Errors​

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized"
}
  • Check that you're including the x-api-key header
  • Verify your API key is correct and not expired
  • Ensure you're using the right API key for your environment

403 Forbidden

{
  "success": false,
  "error": "Insufficient permissions"
}
  • Your API key has Read-Only access but you're trying to modify data
  • Use a Full Access API key for write operations
  • Check your account status and limits

429 Rate Limited

{
  "success": false,
  "error": "Too many requests, please try again later"
}
  • You've exceeded the rate limits for your plan
  • Wait before making additional requests
  • Consider upgrading your plan for higher limits

Debugging Tips​

  1. Double-check the header name: It's x-api-key, not Authorization
  2. Check for extra spaces: API keys should not have leading/trailing whitespace
  3. Test with a simple endpoint: Use GET /api/v1/files to verify authentication

Need help? Contact our support team at support@jsoncut.com.