Authentication

Habito uses API keys for authentication. API keys provide secure, programmatic access to your account without exposing your password.

Generating API Keys

Via Web Interface

1. Navigate to Profile → API Keys
2. Click Generate New API Key
3. Enter a descriptive name (e.g., "CI/CD Bot", "Personal Script")
4. Click Generate
5. Copy the key immediately - it won't be shown again

API Key Format:

hab_f2d4cf18da7978a5b66bd10c2bce080321c1a21527c207bbd2028966460cc757

Keys are prefixed with hab_ followed by 64 hexadecimal characters.

Using API Keys

HTTP Authorization Header

Include your API key in the Authorization header with the Bearer scheme:

GET /api/tasks HTTP/1.1
Host: habito.ar
Authorization: Bearer hab_your_api_key_here
Content-Type: application/json

cURL Example

curl https://habito.ar/api/me \
  -H "Authorization: Bearer hab_f2d4cf18da7978a5b66bd10c2bce080321c1a21527c207bbd2028966460cc757"

JavaScript/Fetch Example

const apiKey = process.env.HABITO_API_KEY

const response = await fetch('https://habito.ar/api/tasks', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})

const data = await response.json()

Python Example

import os
import requests

api_key = os.environ['HABITO_API_KEY']

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get('https://habito.ar/api/tasks', headers=headers)
data = response.json()

Managing API Keys

Viewing Active Keys

Your active API keys are listed in your profile:

• Name: Descriptive label you provided
• Prefix: First 10 characters (hab_f2d4cf...)
• Created: When the key was generated
• Last Used: Most recent API request (updates hourly)

Revoking API Keys

Revoke a key immediately if:

• It's been leaked or exposed publicly
• You no longer need it
• It's associated with a decommissioned project
• You suspect unauthorized access

To revoke:

1. Go to Profile → API Keys
2. Find the key in the list
3. Click Revoke
4. Confirm deletion

What happens when you revoke:

• Key becomes invalid immediately
• All subsequent requests return 401 Unauthorized
• No grace period - take effect instantly

Security Best Practices

Never Expose Keys

❌ DON'T:

• Commit API keys to Git repositories
• Include keys in client-side code
• Share keys in chat or email
• Log keys in application logs
• Store keys in plain text files

✅ DO:

• Use environment variables
• Store in secret management systems (AWS Secrets Manager, HashiCorp Vault)
• Rotate keys periodically (every 90 days)
• Use different keys for different environments

Environment Variables

Development:

# .env file (add to .gitignore!)
HABITO_API_KEY=hab_your_dev_key_here

Production:

# Set in deployment platform
export HABITO_API_KEY=hab_your_prod_key_here

Loading in code:

// Node.js with dotenv
require('dotenv').config()
const apiKey = process.env.HABITO_API_KEY

// Bun/Node native
const apiKey = Bun.env.HABITO_API_KEY

Key Rotation

Rotate API keys regularly to minimize risk:

1. Generate a new key
2. Update applications to use new key
3. Verify applications work with new key
4. Revoke old key
5. Monitor for any failed requests

Rotation Schedule:

• Development keys: Every 90 days
• Production keys: Every 60 days
• Shared keys: Every 30 days
• After security incident: Immediately

Least Privilege

Create separate API keys for different purposes:

✅ "Production App" - for deployed application
✅ "CI/CD Pipeline" - for automated testing
✅ "Personal Scripts" - for one-off scripts
✅ "MCP Integration" - for AI assistants

This allows you to:

• Track usage per integration
• Revoke specific keys without affecting others
• Audit which system made which requests

API Key Permissions

Currently, all API keys have full access to your account:

• Read all your data
• Create/modify/delete tasks
• Create/modify projects and issues
• Join/leave teams
• Update profile information

Rate Limiting

Each API key is subject to rate limits:

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

Rate limit headers in every response:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

When rate limited:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459260

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try again in 60 seconds.",
    "retryAfter": 60
  }
}

Handle rate limits gracefully:

async function makeRequest(url, options) {
  const response = await fetch(url, options)

  if (response.status === 429) {
    const retryAfter = response.headers.get('X-RateLimit-Reset')
    const waitTime = (retryAfter * 1000) - Date.now()

    console.log(`Rate limited. Waiting ${waitTime}ms...`)
    await new Promise(resolve => setTimeout(resolve, waitTime))

    // Retry request
    return makeRequest(url, options)
  }

  return response
}

Authentication Errors

401 Unauthorized

Missing API key:

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authentication required. Provide an API key in the Authorization header."
  }
}

Invalid API key:

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key. Generate a new key from your profile."
  }
}

Revoked API key:

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}

Debugging Authentication

Check your Authorization header:

# Correct format
Authorization: Bearer hab_abc123...

# ❌ Missing "Bearer"
Authorization: hab_abc123...

# ❌ Extra spaces
Authorization: Bearer  hab_abc123...

# ❌ Wrong prefix
Authorization: Basic hab_abc123...

Verify key format:

const apiKey = process.env.HABITO_API_KEY

if (!apiKey) {
  throw new Error('HABITO_API_KEY environment variable not set')
}

if (!apiKey.startsWith('hab_')) {
  throw new Error('Invalid API key format. Must start with "hab_"')
}

if (apiKey.length !== 68) { // "hab_" + 64 chars
  throw new Error('Invalid API key length')
}

OAuth 2.0 (Coming Soon)

For third-party applications that need user authorization:

1. Register your application
2. Redirect user to authorization page
3. Receive authorization code
4. Exchange code for access token
5. Use access token for API requests

Benefits:

• Users don't share API keys with third parties
• Granular permission scopes
• Token expiration and refresh
• User can revoke access anytime

MCP Authentication

For AI assistants using the MCP protocol, see MCP Integration for specific authentication setup.

Security Incident Response

If you suspect your API key was compromised:

1. Immediately revoke the key from your profile
2. Generate a new key with a different name
3. Review recent activity for unauthorized requests
4. Update your applications with the new key
5. Report the incident to [email protected] if needed

FAQ

Q: Can I use the same API key across multiple projects?

A: Yes, but we recommend separate keys for better tracking and security. If one project is compromised, you can revoke its key without affecting others.

Q: Do API keys expire?

A: No, API keys don't expire automatically. You should rotate them regularly as a security best practice.

Q: Can I recover a lost API key?

A: No, for security reasons we don't store the full key. You'll need to generate a new one and update your applications.

Q: What happens to API requests when I revoke a key?

A: They fail immediately with a 401 Unauthorized error. There's no grace period.

Q: How many API keys can I create?

A: Currently unlimited, but we recommend keeping it under 10 active keys for manageability.

Next Steps

• API Overview - Available endpoints
• Tasks API - Task management endpoints
• Projects API - Project & issue management
• MCP Integration - Use with AI assistants