API Authentication

All API requests to Cursed Tools require authentication. We support API token-based authentication with optional encryption keys for accessing encrypted content.

Authentication Methods

API Token Authentication (Required)

All API requests must include an API token in the request header.

Header: X-Cursed-Api-Token

X-Cursed-Api-Token: your-api-token-here

Encryption Key Authentication (Optional, but Recommended)

For accessing encrypted files and analysis results, include your encryption key.

Header: X-Cursed-Api-Enc-Key

X-Cursed-Api-Enc-Key: your-encryption-key-here

Getting Your API Credentials

Step 1: Get API Token

1. Log into your Cursed Tools account
2. Navigate to Settings → General
3. Copy and securely store your token

Step 2: Get Encryption Key (Optional)

1. In the same API settings page
2. Copy your encryption key
3. Store securely alongside your API token

Request Parameters

API Token

Validation Requirements:

• Must be a valid UUID v4 format
• Case-sensitive
• Example: 550e8400-e29b-41d4-a716-446655440000

Example:

X-Cursed-Api-Token: 550e8400-e29b-41d4-a716-446655440000

Encryption Key

When is it Required:

• Using encryption in your workloads
• Accessing encrypted workloads
• Retrieving analysis results from encrypted jobs
• For authenticated users, required when the master encryption key was provided during file upload

Validation Rules:

• Must be base64-encoded string
• Must correspond to your user account
• Must be derived from your authentication credentials
• Case-sensitive

Example:

X-Cursed-Api-Enc-Key: dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGU=

Authentication Examples

cURL

# Basic authentication
curl -X GET "https://api.cursed.tools/analysis/file/list" \
  -H "X-Cursed-Api-Token: 550e8400-e29b-41d4-a716-446655440000"

# With encryption key
curl -X GET "https://api.cursed.tools/analysis/job/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Cursed-Api-Token: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Cursed-Api-Enc-Key: dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGU="

# With POST
curl -X POST "https://api.cursed.tools/analysis/file/delete" \
  -H "X-Cursed-Api-Token: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["file-uuid-here"]}'

Authentication Errors

Common Error Responses

All error responses return a plain text message with an appropriate HTTP status code.

Missing API Token

Status Code: 401 Unauthorized Response: Unauthorized

Invalid API Token Format

Status Code: 400 Bad Request Response: X-Cursed-Api-Token must be a valid UUID v4

Invalid API Token

Status Code: 401 Unauthorized Response: Invalid API token

Account Not Activated

Status Code: 401 Unauthorized Response: Account not activated, please check your email for activation instructions

Missing Encryption Key (when required)

Status Code: 400 Bad Request Response: Encryption key is required

Invalid Encryption Key Format

Status Code: 400 Bad Request Response: X-Cursed-Api-Enc-Key is invalid

Invalid Encryption Key (when decrypting)

Status Code: 500 Internal Server Error Response: An error occurred while processing your request. If you would like to report it contact us via the feedback form on cursed.tools/feedback and quote the following ID: [error-uuid]

Security Best Practices

Secure Storage

• Never commit tokens to version control
• Use environment variables or secure vaults
• Rotate tokens regularly (recommended: every 90 days)
• Revoke unused or compromised tokens immediately

Header Validation

• Verify token format: Must be valid UUID v4
• Verify encryption key format: Must be valid base64

Troubleshooting

Common Issues

Token Not Working

1. Check token format - Must be valid UUID v4 (not just any UUID)
2. Verify account status - Account must be active
3. Check header name - Must be X-Cursed-Api-Token
4. Verify case sensitivity - Tokens are case-sensitive

Encryption Key Issues

1. Verify key format - Must be base64-encoded
2. Check header name - Must be X-Cursed-Api-Enc-Key
3. Matching token with web UI - Validate that the key matches your account settings
4. Test with simple request - Verify your API token works without encryption key first

Getting Help

If you continue to experience authentication issues:

• Review logs: Check for detailed error messages
• Contact support: [email protected]
• Include in subject: "API Authentication Issue"

Proper authentication is essential for accessing the Cursed Tools API securely. Always follow security best practices when handling API credentials.