API REST pública

Use a API REST pública do cside para provisionar equipes e domínios gerenciados em um fluxo de backend. A API usa JSON por HTTPS e um token bearer no nível da organização.

URL base: https://api.cside.com

Fluxo de provisionamento

A criação de equipes e o registro de domínios são operações separadas:

1. Crie um token de API da organização com as permissões necessárias
2. Chame POST /v1/teams/ e salve o teamId retornado
3. Chame POST /v1/domains/ com esse teamId e até 100 nomes de host
4. Verifique cada item em data.results antes de considerar o provisionamento concluído

Se o registro de domínios falhar, a equipe continuará disponível. A API não reverte uma criação de equipe bem-sucedida.

Disponibilidade e autenticação

Um administrador da organização pode gerar um token em Configurações da organização > Geral no dashboard do cside. Escolha apenas as permissões necessárias para a integração:

Permissão	Acesso à API
Criar equipes (teams:create)	POST /v1/teams/
Registrar domínios (domains:create)	POST /v1/domains/
Excluir domínios (domains:delete)	DELETE /v1/domains/

O dashboard mostra cada token apenas uma vez. Armazene-o em um gerenciador de segredos do servidor antes de fechar a caixa de diálogo. Não o exponha no código do navegador, não o envie ao controle de versão, e não o grave em logs da aplicação.

Envie o token em todas as requisições:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Os tokens permanecem válidos até que um administrador selecione Revogar todos os tokens. Essa ação invalida imediatamente todos os tokens de API da organização.

Limite de requisições

A API aceita 60 requisições por organização a cada minuto. Esse limite é compartilhado entre os endpoints de equipe e domínio. Uma requisição acima do limite retorna 429 com o código de erro rate_limited. Tente novamente com backoff depois que o próximo minuto começar.

Criar uma equipe

Use POST /v1/teams/ para criar uma equipe na organização à qual o token pertence.

curl --request POST \
  --url https://api.cside.com/v1/teams/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Acme Production"
  }'

O nome da equipe deve:

• Conter de 3 a 32 caracteres
• Usar letras, números, sublinhados, espaços, ou apóstrofos
• Ser exclusivo dentro da organização

Hífens não são aceitos em nomes de equipe.

Uma requisição bem-sucedida retorna 201 Created:

{
  "data": {
    "teamId": "1897425263682514944"
  }
}

Salve data.teamId. Você precisará dele para registrar ou excluir domínios da equipe.

Criar uma equipe não habilita o onboarding automático de domínios. Esse recurso é configurado separadamente para cada equipe e fica desabilitado por padrão.

Registrar domínios

Use POST /v1/domains/ para registrar de 1 a 100 nomes de host como domínios gerenciados de uma equipe. team_id é obrigatório ao usar um token de API da organização.

curl --request POST \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "checkout.example.com",
      "app.example.com"
    ]
  }'

Envie nomes de host sem protocolo, porta, caminho, string de consulta, ou fragmento. O cside remove os espaços em branco e normaliza os nomes de host aceitos para letras minúsculas.

Cada item registra exatamente o nome de host enviado. A API não cria um domínio wildcard. Portanto, inclua todos os nomes de host necessários, como example.com e www.example.com.

O endpoint retorna 200 OK com um resultado para cada entrada, na mesma ordem:

{
  "data": {
    "results": [
      {
        "status": "created",
        "input": "checkout.example.com",
        "domain": "checkout.example.com",
        "domainId": "1897425263682514945"
      },
      {
        "status": "existing",
        "input": "app.example.com",
        "domain": "app.example.com",
        "domainId": "1897425263682514946"
      },
      {
        "status": "invalid",
        "input": "not a hostname",
        "code": "invalid_domain",
        "message": "Domain is invalid."
      }
    ],
    "totals": {
      "created": 1,
      "existing": 1,
      "invalid": 1
    }
  }
}

A requisição pode conter resultados bem-sucedidos e inválidos e ainda retornar 200 OK. Verifique cada resultado:

Status	Significado
created	O cside registrou o nome de host e retornou seu novo domainId
existing	A mesma equipe já gerencia o nome de host. O domainId original é retornado
invalid	O cside não registrou o nome de host. Consulte code e message

É seguro repetir requisições para domínios que já foram criados para a mesma equipe. Elas retornam existing em vez de criar uma duplicata. Um nome de host gerenciado por outra equipe retorna invalid com domain_already_licensed.

Novos domínios passam a contar automaticamente com proteção gerenciada. Não é necessária uma chamada separada à API para ativação. A configuração pode levar algum tempo para chegar à rede de distribuição.

Códigos de validação de domínio

Um resultado invalid pode incluir um destes códigos:

Código	Significado
empty_domain	A entrada está vazia
invalid_domain	O nome de host não é válido
public_suffix_domain	A entrada é um sufixo público, e não um nome de host registrável
internal_domain	O nome de host é reservado ou não permitido
reserved_ip	O DNS resolve o nome de host para um endereço IP reservado
wildcard_conflict	Um domínio wildcard existente já abrange esse nome de host
subdomain_conflict	Uma configuração de domínio existente já inclui esse subdomínio
domain_already_licensed	Outra equipe já gerencia o nome de host
internal_error	O cside não conseguiu validar ou criar o domínio

Carregar o cside para a equipe

Use o teamId retornado pela criação da equipe na URL padrão do script do cside. Não use um domainId no lugar dele.

<script
  src="https://[your-team-id].csidetm.com/client.js"
  referrerpolicy="origin">
</script>

O nome de host da página deve estar registrado no mesmo ID de equipe usado na URL do script. A ausência do registro ou uma incompatibilidade de equipe retorna 403. Se isso ocorrer logo após o registro, tente novamente em alguns instantes. Entre em contato com o suporte do cside se o problema continuar.

O monitoramento padrão não exige um CNAME do cliente nem redirecionamento de tráfego. Se o seu site tiver uma Content Security Policy restritiva, siga o guia de configuração da CSP para permitir *.csidetm.com.

Onboarding automático de domínios

O onboarding automático de domínios é um recurso opcional da equipe para implantações que carregam o script de bootstrap padrão do cside. Ele fica desabilitado por padrão para novas equipes. Entre em contato com seu representante do cside se precisar habilitá-lo.

Quando o recurso está habilitado e um nome de host não registrado carrega o bootstrap específico da equipe em /client.js ou /script.js, o cside envia o nome de host de referência pelo mesmo fluxo de validação e registro de domínio. Mantenha o atributo padrão referrerpolicy="origin" para que a origem da página fique disponível sem expor seu caminho ou sua string de consulta.

A requisição que detecta o nome de host não registrado não é repetida. O registro afeta uma requisição de script posterior, depois que a configuração é propagada. Domínios registrados automaticamente aparecem no inventário de domínios da equipe da mesma forma que os domínios registrados pela API.

O onboarding automático não cria equipes, e requisições a outros endpoints do cside não registram um nome de host. Use o fluxo explícito da API quando precisar de um resultado para cada domínio antes de implantar o script. O onboarding automático se aplica ao script de monitoramento padrão e não habilita a coleta de Device Intelligence.

Excluir domínios

Use DELETE /v1/domains/ com os valores domainId retornados pelo registro de domínios. Não envie nomes de host para esse endpoint.

curl --request DELETE \
  --url https://api.cside.com/v1/domains/ \
  --header "Authorization: Bearer $CSIDE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "team_id": "1897425263682514944",
    "domains": [
      "1897425263682514945",
      "1897425263682514946"
    ]
  }'

Você pode enviar de 1 a 100 IDs de domínio. Uma requisição bem-sucedida retorna resultados parciais ordenados:

{
  "data": {
    "results": [
      {
        "status": "deleted",
        "domainId": "1897425263682514945",
        "domain": "checkout.example.com"
      },
      {
        "status": "not_found",
        "domainId": "1897425263682514999"
      }
    ],
    "totals": {
      "deleted": 1,
      "not_found": 1
    }
  }
}

A exclusão é idempotente. Um ID desconhecido, um domínio já excluído, ou um domínio fora da equipe de destino retorna not_found sem expor informações sobre outra equipe.

Erros no nível da requisição

As falhas no nível da requisição usam este formato:

{
  "error": "insufficient_scope",
  "message": "Token is missing the domains:create scope."
}

Status HTTP	Códigos de erro comuns	Ação
400	invalid_request	Verifique o corpo JSON, os campos obrigatórios, as strings de ID, e os limites de itens
401	unauthorized	Verifique o token bearer e se todos os tokens da organização foram revogados
403	insufficient_scope, enterprise_required, erros de suspensão	Verifique as permissões do token, o acesso ao plano, e o status da conta
404	team_not_found	Confirme se o ID da equipe pertence à organização do token
409	team_name_exists	Escolha um nome de equipe exclusivo ou use a equipe existente
429	rate_limited	Tente novamente com backoff após a janela atual do limite de requisições
503	rate_limit_unavailable, domain_deletion_unavailable	Tente novamente mais tarde. Entre em contato com o suporte do cside se o erro continuar

Checklist de segurança

• Gere um token separado para cada integração de backend
• Conceda apenas as permissões necessárias para essa integração
• Armazene os tokens em um gerenciador de segredos do servidor
• Nunca exponha tokens no código do navegador, em URLs, no controle de versão, ou em logs
• Revogue imediatamente todos os tokens da organização se um deles for exposto
• Trate os IDs de equipe e domínio retornados como strings

Documentação relacionada

• Referência interativa da API
• Adicionar seu domínio
• Adicionar o script do cside
• Configurações do dashboard