Authentication

All Archyl API requests require authentication using an API key. This guide explains how to create and use API keys.

Creating an API Key

Log in to your Archyl account
Go to Profile > API Keys
Click Create API Key
Configure your key:
- Name: A descriptive name (e.g., "CI/CD Pipeline", "Local Development")
- Permissions: Read-only or Read-Write
- Expiration: Optional expiration date
Click Create
Copy and save the key immediately - it won't be shown again

API Key Permissions

Permission	Capabilities
Read	View projects, elements, documentation, and architecture data
Write	Create, update, and delete projects, elements, and documentation

Choose the minimum permissions required for your use case.

Using Your API Key

Include your API key in the X-API-Key header with every request:

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

Example: List Projects

curl -X GET \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

Example: Create a System

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "description": "Handles payment processing",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

MCP Server Authentication

When using the MCP Server with AI assistants, authentication works the same way:

Claude Code / Claude Desktop

Add your API key to the MCP configuration:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Security Best Practices

Protect Your Keys

Never commit API keys to version control
Use environment variables in CI/CD pipelines
Rotate keys periodically
Use separate keys for different environments

Environment Variables

# Store in .env (add to .gitignore)
ARCHYL_API_KEY=your-api-key

# Use in scripts
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

CI/CD Integration

Store your API key as a secret in your CI/CD platform:

GitHub Actions:

- name: Update Architecture
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI:

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Managing API Keys

Viewing Keys

Go to Profile > API Keys to see all your active keys:

Key name and creation date
Permission level
Expiration status
Last used timestamp

Revoking Keys

To revoke a compromised or unused key:

Go to Profile > API Keys
Find the key to revoke
Click Revoke
Confirm the action

Revoked keys are immediately invalidated.

Key Expiration

Keys can be set to expire:

Never: Key remains valid until manually revoked
30 days: Good for temporary access
90 days: Balanced security and convenience
Custom: Set any expiration date

Error Responses

Invalid or Missing Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

HTTP Status: 401 Unauthorized

Insufficient Permissions

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have write permissions"
  }
}

HTTP Status: 403 Forbidden

Expired Key

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