Autenticação

Todas as requisições à API do Archyl exigem autenticação usando uma chave de API. Este guia explica como criar e usar chaves de API.

Criando uma Chave de API

Faça login na sua conta Archyl
Vá para Perfil > Chaves de API
Clique em Criar Chave de API
Configure sua chave:
- Nome: Um nome descritivo (ex.: "Pipeline CI/CD", "Desenvolvimento Local")
- Permissões: Somente leitura ou Leitura e escrita
- Expiração: Data de expiração opcional
Clique em Criar
Copie e salve a chave imediatamente — ela não será exibida novamente

Permissões da Chave de API

Permissão	Capacidades
Leitura	Visualizar projetos, elementos, documentação e dados de arquitetura
Escrita	Criar, atualizar e excluir projetos, elementos e documentação

Escolha as permissões mínimas necessárias para o seu caso de uso.

Usando Sua Chave de API

Inclua sua chave de API no header X-API-Key em cada requisição:

curl -H "X-API-Key: sua-chave-de-api" \
  https://api.archyl.com/api/v1/projects

Exemplo: Listar Projetos

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

Exemplo: Criar um Sistema

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

Autenticação do Servidor MCP

Ao usar o Servidor MCP com assistentes de IA, a autenticação funciona da mesma forma:

Claude Code / Claude Desktop

Adicione sua chave de API à configuração MCP:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "sua-chave-de-api"
      }
    }
  }
}

Cursor

Em .cursor/mcp.json:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "sua-chave-de-api"
      }
    }
  }
}

Boas Práticas de Segurança

Proteja Suas Chaves

Nunca faça commit de chaves de API no controle de versão
Use variáveis de ambiente em pipelines CI/CD
Faça a rotação de chaves periodicamente
Use chaves separadas para diferentes ambientes

Variáveis de Ambiente

# Armazene em .env (adicione ao .gitignore)
ARCHYL_API_KEY=sua-chave-de-api

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

Integração CI/CD

Armazene sua chave de API como um segredo na sua plataforma de CI/CD:

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

Gerenciando Chaves de API

Visualizando Chaves

Vá para Perfil > Chaves de API para ver todas as suas chaves ativas:

Nome da chave e data de criação
Nível de permissão
Status de expiração
Data/hora do último uso

Revogando Chaves

Para revogar uma chave comprometida ou não utilizada:

Vá para Perfil > Chaves de API
Encontre a chave a ser revogada
Clique em Revogar
Confirme a ação

Chaves revogadas são invalidadas imediatamente.

Expiração de Chaves

As chaves podem ser configuradas para expirar:

Nunca: A chave permanece válida até ser revogada manualmente
30 dias: Bom para acesso temporário
90 dias: Equilíbrio entre segurança e conveniência
Personalizado: Defina qualquer data de expiração

Respostas de Erro

Chave Inválida ou Ausente

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

Status HTTP: 401 Unauthorized

Permissões Insuficientes

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

Status HTTP: 403 Forbidden

Chave Expirada

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