Authentication

The CommitKey API uses API key authentication for all requests. This guide explains how to obtain and use API keys.

API Keys

API keys are the primary method of authentication for the CommitKey API. Each API key is associated with a specific user account and has its own permissions and rate limits.

Creating an API Key

1. Sign in to your CommitKey account
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Give your key a descriptive name
5. Select the appropriate permissions
6. Click Create Key

Important: Copy the API key immediately after creation. It won't be shown again for security reasons.

Using API Keys

Include your API key in the Authorization header of all requests:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.commitkey.dev/v1/repositories

Key Permissions

API keys can have different permission levels:

• Read: Can read repositories, commits, and other data
• Write: Can create and modify repositories and commits
• Admin: Full access including account management

Key Management

• Rotate Keys: Regularly rotate your API keys for security
• Monitor Usage: Check API key usage in your dashboard
• Revoke Keys: Immediately revoke compromised keys

Scoped Access

For enhanced security, you can create API keys with limited scope:

Repository Scoped Keys

Limit access to specific repositories:

{
  "permissions": ["read", "write"],
  "repositories": ["repo-1", "repo-2"]
}

Organization Scoped Keys

Limit access to specific organizations:

{
  "permissions": ["read"],
  "organizations": ["org-1"]
}

Best Practices

Security

• Never commit API keys to version control
• Use environment variables to store keys
• Rotate keys regularly
• Monitor key usage for suspicious activity

Environment Variables

Store your API key in environment variables:

export COMMITKEY_API_KEY="your_api_key_here"

const apiKey = process.env.COMMITKEY_API_KEY;

Key Rotation

Regularly rotate your API keys:

1. Create a new API key
2. Update your applications to use the new key
3. Test that everything works
4. Revoke the old key

Error Handling

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Expired API Key

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "The API key has expired"
  }
}

Insufficient Permissions

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "The API key does not have permission to perform this action"
  }
}

Next Steps

• API Reference - Complete API documentation
• Rate Limits - Understanding API limits
• SDKs - Use our official SDKs