Autenticação

Para acessar a API do Studio, você precisa de uma chave de API. O Studio oferece dois tipos de chave — chaves pessoais e chaves de workspace — cada um com comportamentos diferentes de cobrança e de acesso.

Tipos de chave

Como gerar chaves de API

Para gerar uma chave pessoal, abra Account settings → Studio API keys. Administradores do workspace podem criar chaves compartilhadas em Workspace settings → Studio API keys.

Como usar as chaves de API

Envie sua chave de API no header X-API-Key em toda requisição:

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"input": {}}'

const response = await fetch(
  'https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.STUDIO_API_KEY!,
    },
    body: JSON.stringify({ input: {} }),
  }
)

import os
import requests

response = requests.post(
    "https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["STUDIO_API_KEY"],
    },
    json={"input": {}},
)

Escopo de workspace

Toda requisição que nomeia um workspace é verificada contra o escopo da própria chave antes de qualquer leitura de dados. Os dois tipos de chave têm escopos diferentes:

• Uma chave de workspace nunca alcança nada além do próprio workspace. Se a requisição nomear um workspaceId diferente, a API responde 403 com API key is not authorized for this workspace e para aí — nenhuma consulta é executada, e a resposta não revela nada sobre a existência do outro workspace. Isso vale em todos os endpoints de todas as versões da API, e não é algo que um administrador de workspace possa liberar.
• Uma chave pessoal só alcança um workspace quando aquele workspace permite. Cada workspace tem a configuração Allow personal API keys. Com ela desligada, uma chave pessoal é recusada com 403 e Personal API keys are not allowed for this workspace, mesmo que o dono da chave seja membro. Com ela ligada, a chave continua limitada ao nível de permissão do dono naquele workspace — um endpoint de leitura exige read, um de escrita exige write — e uma chave cujo dono não tem nenhum dos dois é recusada com 403 e Access denied.

Um 403 nunca diz se um recurso existe no workspace que você não conseguiu alcançar. Os recursos são sempre resolvidos dentro de workspaceId, então uma conversa ou um contato que vive em outro workspace é reportado como 404 (não encontrado), e não como acesso negado.

Onde as chaves são usadas

As chaves de API autenticam o acesso a:

• Execução de workflows — execute pela API os workflows que já têm deploy
• API de Logs — consulte logs e métricas de execução de workflows
• Servidores MCP — autentique conexões com servidores MCP com deploy
• API do Chat — leia e escreva conversas, mensagens, contatos e equipes na caixa de entrada de um workspace
• SDKs — os SDKs Python e TypeScript usam chaves de API em todas as operações

Segurança

• As chaves usam o prefixo sk-studio- e são criptografadas em repouso
• As chaves podem ser revogadas a qualquer momento pelo dashboard
• Use variáveis de ambiente para guardar as chaves — nunca as escreva direto no código-fonte
• Em aplicações que rodam no navegador, use um proxy de backend para não expor as chaves ao cliente