API Authentication

CodeInput provides a RESTful API that allows you to integrate our merge conflict resolution capabilities into your own tools and workflows. This guide covers the authentication methods available.

Authentication Methods

CodeInput supports two primary authentication methods:

1. OAuth 2.0 (recommended for user-facing applications)
2. API Keys (recommended for server-to-server integrations)

OAuth 2.0 Authentication

OAuth 2.0 is the recommended method for applications that act on behalf of users.

Authorization Flow

1. Direct Users to Authorization URL

2. Handle the Callback

After authorization, users are redirected to your redirect_uri with an authorization code:

3. Exchange Code for Access Token

curl -X POST https://api.codeinput.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "scope": "repo:read conflicts:write"
}

Using Access Tokens

Include the access token in the Authorization header:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.codeinput.com/v1/repositories

Refreshing Tokens

When your access token expires, use the refresh token:

curl -X POST https://api.codeinput.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

API Key Authentication

API keys are ideal for server-to-server integrations and automated scripts.

Creating API Keys

1. Go to your CodeInput dashboard
2. Navigate to Settings > API Keys
3. Click "Generate New API Key"
4. Set the permissions and expiration
5. Copy the generated key (it won't be shown again)

Using API Keys

Include the API key in the X-API-Key header:

curl -H "X-API-Key: ci_your_api_key_here" \
  https://api.codeinput.com/v1/repositories

API Key Scopes

When creating API keys, you can limit their permissions:

• repo:read - Read repository information
• repo:write - Modify repository settings
• conflicts:read - View merge conflicts
• conflicts:write - Resolve merge conflicts
• analytics:read - Access analytics data
• team:read - View team information
• team:write - Manage team members

Scopes and Permissions

Available Scopes

Checking Token Permissions

You can verify your token's permissions:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.codeinput.com/v1/user/permissions

Response:

{
  "scopes": ["repo:read", "conflicts:write"],
  "user": {
    "id": "user_123",
    "login": "username",
    "email": "user@example.com"
  },
  "rate_limit": {
    "limit": 5000,

Rate Limiting

API requests are subject to rate limiting:

• OAuth tokens: 5,000 requests per hour
• API keys: 10,000 requests per hour
• Free tier: 1,000 requests per hour

Rate limit headers are included in all responses:

Error Handling

Authentication Errors

Invalid Token

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired",
  "status": 401
}

Insufficient Permissions

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token",
  "status": 403
}

Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "error_description": "API rate limit exceeded",
  "status": 429,
  "retry_after": 3600
}

Best Practices

Security

• Store tokens securely (environment variables, secure key management)
• Use HTTPS for all API requests
• Rotate API keys regularly
• Use minimal required scopes

Error Handling

• Implement proper retry logic for rate limits
• Handle token expiration gracefully
• Log authentication errors for debugging

Performance

• Cache tokens until expiration
• Use API keys for high-frequency server-to-server calls
• Implement request batching where possible

Example Implementation

Here's a simple Node.js example:

class CodeInputAPI {
  constructor(accessToken) {
    this.token = accessToken;
    this.baseURL = 'https://api.codeinput.com/v1';
  }

  async makeRequest(endpoint, method = 'GET', data = null) {
    const response = await fetch(`${this.baseURL}${endpoint}`, {
      method,