Authentication

All CraftDesk API requests require authentication using Bearer tokens. This guide covers generating, managing, and securing your API keys.

Generating API Keys

API keys are the credentials used to authenticate API requests. Generate them in the CraftDesk dashboard:

1. Log in to your workspace
2. Go to Settings → Integrations → API Keys
3. Click Generate New Key
4. Give your key a descriptive name (e.g., "CI/CD Pipeline", "Mobile App")
5. Click Generate
6. Copy and store the key immediately — You won't see it again

The key appears only once. If you lose it, you must generate a new key and update any integrations using the old one.

Using API Keys

Include your API key in the Authorization header of every request:

Authorization: Bearer your_api_key_here

Example with cURL

curl https://api.craftdesk.app/v1/projects \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Example with Python

import requests

headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.craftdesk.app/v1/projects",
    headers=headers
)

projects = response.json()

Example with JavaScript

const apiKey = "your_api_key_here";

fetch("https://api.craftdesk.app/v1/projects", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

Scoped Keys

When creating a new API key, you can optionally restrict its scope:

Full Access — The key can read and write all data in your workspace. Equivalent to the creator's permission level.

Read-Only — The key can only read data. It cannot create, update, or delete resources. Useful for public integrations or third-party services that only need data access.

Custom Scope (Business plan only) — Restrict keys to specific projects or resource types. Examples:

• Read-only access to a specific project
• Write access to project tasks only
• No access to team member data

Scoped keys limit potential damage if a key is compromised.

Key Security Practices

Never share keys — Treat API keys like passwords. Never commit them to version control or share in email.

Use environment variables — Store keys in .env files or secret management systems, not in source code:

# .env
CRAFTDESK_API_KEY=your_api_key_here

import os
api_key = os.getenv("CRAFTDESK_API_KEY")

Rotate regularly — Regenerate keys every 90 days, especially for production integrations.

Use scoped keys — Create read-only keys for public-facing apps and limit scope to necessary resources.

Monitor usage — Check your API usage in the dashboard to detect unusual activity.

Revoke immediately — If a key is compromised, revoke it immediately from the API Keys page.

Managing Keys

In Settings → Integrations → API Keys, you can:

View All Keys — See all active API keys with their creation date and last used date. Helps identify unused keys that should be revoked.

Rename Keys — Change a key's name for clarity without affecting functionality.

View Usage — See how many API calls each key has made in the current billing period.

Revoke Keys — Disable a key immediately. Any integrations using it will start receiving 401 (Unauthorized) errors.

Revoking and Rotating Keys

When it's time to rotate a key:

1. Generate a new API key
2. Update all applications using the old key to use the new one
3. Test thoroughly that the new key works
4. Revoke the old key

This process ensures zero downtime during key rotation.

Troubleshooting Authentication

401 Unauthorized

Your API key is missing, invalid, or expired. Check:

• The key is included in the Authorization header
• The header format is Bearer key_value
• The key hasn't been revoked
• The key belongs to the correct workspace

403 Forbidden

Your API key is valid but doesn't have permission for this resource. This happens with:

• Read-only keys trying to create/update resources
• Scoped keys accessing unauthorized projects
• Insufficient workspace permissions (if created by a Member)

429 Too Many Requests

You've exceeded your rate limit for this billing period. Either:

• Wait until the next billing cycle
• Upgrade to a plan with higher limits
• Optimize your request pattern to use fewer calls

Tokens and OAuth

CraftDesk currently supports API keys only. OAuth support is planned for future releases. Contact support if you need enterprise authentication options.

What's Next

• API Overview — Start with the API
• Webhooks — Build real-time integrations
• API Reference — Complete endpoint documentation (craftdesk.app/api/docs)