Verk

API Keys

Creating API keys, permissions, usage monitoring

API Keys & Access Tokens

Generate API keys for programmatic access to Verk. Create secure tokens, manage permissions, and monitor API usage.

Overview

API keys enable:

  • Programmatic access to your Verk data
  • Integration with third-party tools
  • Custom automation scripts
  • CI/CD pipeline integration
  • Webhook authentication

Each API key can have specific permissions and rate limits.

Prerequisites

Required role: Any user can create personal API keys Plan requirements:

  • Free: 2 API keys, 1,000 requests/day
  • Pro: 10 API keys, 100,000 requests/day
  • Enterprise: Unlimited keys and requests

API keys provide programmatic access to your account. Keep them secret and secure like passwords.

Creating API Keys

Generate Your First Key

Create a new API key:

  1. Navigate to Settings → API Keys
  2. Click "+ Create API Key"
  3. Configure the key:
  • Name: Descriptive name (e.g., "CI/CD Pipeline", "Data Export Script")
  • Description: Purpose and usage context
  • Expiration: Never, 30 days, 90 days, 1 year, custom date
  • Permissions: Select scope (read, write, delete)
  1. Click "Generate Key"
  2. Copy the API key immediately

API keys are shown only once during creation. Copy and save them securely. You cannot retrieve them later.

Key format:

verk_sk_live_AbCdEfGh123456789
  • verk: Platform identifier
  • sk: Secret key
  • live: Environment (live or test)
  • AbCdEfGh123456789: Unique identifier

Permission Scopes

Choose what the API key can access:

Read permissions:

  • tasks:read - View tasks
  • projects:read - View projects
  • members:read - View team members
  • files:read - Download files
  • comments:read - View comments
  • analytics:read - Access analytics data

Write permissions:

  • tasks:write - Create and update tasks
  • projects:write - Create and update projects
  • files:write - Upload files
  • comments:write - Add comments
  • webhooks:write - Create webhooks

Delete permissions:

  • tasks:delete - Delete tasks
  • projects:delete - Delete projects
  • files:delete - Delete files

Full access:

  • * - All permissions (use carefully)

Best practice: Grant minimum permissions needed. Use read-only when possible.

Setting Expiration

Control key lifespan:

Never expire:

  • Key remains active indefinitely
  • Requires manual revocation
  • Higher security risk
  • Only for long-term integrations

Time-limited:

  • Auto-expires after period
  • Reduces risk if key is compromised
  • Requires renewal for continued access
  • Recommended for most use cases

Custom expiration: Choose specific date (e.g., end of project, contract period)

Using API Keys

Authentication

Include your API key in requests:

Header authentication (recommended):

curl -X GET "https://api.verk.com/v1/tasks" \
 -H "Authorization: Bearer verk_sk_live_AbCdEfGh123456789"

Query parameter (not recommended):

curl "https://api.verk.com/v1/tasks?api_key=verk_sk_live_AbCdEfGh123456789"

Query parameters appear in logs and browser history. Always use header authentication.

Example Requests

Get all tasks:

curl -X GET "https://api.verk.com/v1/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json"

Create a task:

curl -X POST "https://api.verk.com/v1/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "title": "Implement new feature",
 "description": "Add user authentication",
 "projectId": "proj_123",
 "priority": "high",
 "dueDate": "2024-12-31"
 }'

Update a task:

curl -X PATCH "https://api.verk.com/v1/tasks/task_456" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "status": "in_progress",
 "assigneeId": "user_789"
 }'

Rate Limits

API requests are rate-limited by plan:

Free plan:

  • 1,000 requests per day
  • 100 requests per hour
  • 10 requests per minute

Pro plan:

  • 100,000 requests per day
  • 10,000 requests per hour
  • 500 requests per minute

Enterprise plan:

  • Custom limits based on contract
  • Typically unlimited for standard usage

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200

Exceeding limits:

  • HTTP 429 Too Many Requests
  • Retry after time indicated in Retry-After header
  • Implement exponential backoff

Error Handling

Handle API errors gracefully:

Common status codes:

  • 200 OK - Success
  • 201 Created - Resource created
  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource doesn't exist
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server issue

Error response format:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: title",
    "param": "title",
    "type": "validation_error"
  }
}

Managing API Keys

Viewing Active Keys

See all your API keys:

  1. Navigate to Settings → API Keys
  2. View key list showing:
  • Key name and description
  • Created date
  • Last used date
  • Expiration date
  • Permissions
  • Usage stats

Key details: Click any key to see:

  • Full permission list
  • Request count (last 7 days, 30 days)
  • Last request timestamp
  • Associated IP addresses
  • Error rate

Rotating Keys

Periodically update API keys for security:

Create rotation process:

  1. Generate new API key with same permissions
  2. Update applications to use new key
  3. Test new key works correctly
  4. Revoke old key
  5. Monitor for errors

Recommended rotation:

  • Production keys: Every 90 days
  • Development keys: Every 180 days
  • Unused keys: Revoke immediately

Zero-downtime rotation:

  1. Create new key (Key B)
  2. Deploy Key B to 50% of services
  3. Monitor for issues
  4. Deploy Key B to remaining 50%
  5. Wait 7 days for propagation
  6. Revoke old key (Key A)

Revoking Keys

Disable compromised or unused keys:

  1. Find key in API Keys list
  2. Click "Revoke"
  3. Confirm revocation

What happens:

  • Key immediately stops working
  • All requests return 401 Unauthorized
  • Applications using key will fail
  • Cannot be undone - must create new key

When to revoke:

  • Key potentially compromised
  • Employee leaving company
  • Application decommissioned
  • Key no longer needed
  • Transitioning to new key

Monitoring Usage

Usage Analytics

Track API key activity:

Dashboard metrics:

  • Total requests (by day, week, month)
  • Success rate
  • Error rate by type
  • Average response time
  • Top endpoints used

Request breakdown:

  • GET requests (read operations)
  • POST requests (create operations)
  • PATCH/PUT requests (update operations)
  • DELETE requests (delete operations)

Filtering:

  • By date range
  • By endpoint
  • By response code
  • By IP address

Usage Alerts

Get notified of unusual activity:

Alert triggers:

  • Approaching rate limit (80%, 90%)
  • Unusual number of errors (>5% error rate)
  • Request from new IP address
  • Spike in usage (2x normal)
  • Key used after business hours

Configure alerts:

  1. Settings → API Keys → Alerts
  2. Enable desired alerts
  3. Add notification emails
  4. Set thresholds
  5. Save

Security Best Practices

Never Commit Keys to Version Control Add API keys to .gitignore and use environment variables instead:

# .env file (add to .gitignore)
VERK_API_KEY=verk_sk_live_AbCdEfGh123456789
// Use environment variable
const apiKey = process.env.VERK_API_KEY

Use Environment Variables Store keys in environment variables, not in code:

export VERK_API_KEY="verk_sk_live_AbCdEfGh123456789"

Separate Keys by Environment Use different API keys for development, staging, and production.

Grant Minimal Permissions Only assign permissions absolutely necessary for the integration.

Rotate Keys Regularly Change production API keys every 90 days, development keys every 180 days.

Monitor Key Usage Review usage logs weekly for unusual activity or errors.

Revoke Unused Keys Remove API keys that haven't been used in 90+ days.

Use HTTPS Only Always send API requests over HTTPS, never HTTP.

Implement Rate Limiting Add your own rate limiting to avoid hitting Verk's limits.

Log but Don't Store Log API requests for debugging but never log the full API key.

Troubleshooting

API Key Not Working

Check:

  • Key hasn't been revoked
  • Key hasn't expired
  • Permissions include required scope
  • Rate limit not exceeded
  • Correct API endpoint URL
  • Proper authentication header format

Common mistakes:

# Wrong - missing Bearer prefix
Authorization: verk_sk_live_AbCdEfGh123456789

# Correct - includes Bearer
Authorization: Bearer verk_sk_live_AbCdEfGh123456789

401 Unauthorized Error

Causes:

  • Invalid API key
  • Expired key
  • Revoked key
  • Missing Authorization header
  • Typo in API key

Fix:

  1. Verify key is copied correctly (no extra spaces)
  2. Check key hasn't expired
  3. Confirm key is still active in dashboard
  4. Test with curl to isolate issue

403 Forbidden Error

Causes:

  • Insufficient permissions
  • Attempting to access resource outside scope
  • Organization-level restrictions

Fix:

  1. Review key permissions
  2. Add required scope
  3. Confirm you have access to the resource
  4. Check organization settings

Rate Limit Exceeded

Solutions:

  • Implement exponential backoff
  • Cache responses when possible
  • Batch operations
  • Upgrade plan for higher limits
  • Spread requests over longer time period

Exponential backoff example:

async function makeRequestWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, {
        headers: { Authorization: `Bearer ${apiKey}` },
      })

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After')
        const delay = retryAfter
          ? parseInt(retryAfter) * 1000
          : Math.pow(2, i) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      return response
    } catch (error) {
      if (i === maxRetries - 1) throw error
    }
  }
}

Related Documentation

Need API support? Check our API documentation or contact our developer support.

On this page

API Keys & Access TokensOverviewPrerequisitesCreating API KeysGenerate Your First KeyPermission ScopesSetting ExpirationUsing API KeysAuthenticationExample RequestsRate LimitsError HandlingManaging API KeysViewing Active KeysRotating KeysRevoking KeysMonitoring UsageUsage AnalyticsUsage AlertsSecurity Best PracticesTroubleshootingAPI Key Not Working401 Unauthorized Error403 Forbidden ErrorRate Limit ExceededRelated Documentation