Autenticação

Envie sua chave hm_live_ como token Bearer: como criar chaves, escolher escopos, definir validade, fazer rotação e revogar, e o que cada erro significa.

Atualizado em 18 de outubro de 2026

Toda requisição à HILLS API envia uma chave de API no header Authorization. Não há sessões nem cookies: a API ignora cookies e não envia headers CORS. Chame-a apenas a partir do seu servidor.

A chave

Uma chave tem o formato hm_live_ seguido de 48 caracteres hexadecimais. Existe um único tipo de chave. Ela lê e age sobre a sua conta de cliente e os artistas e gravadoras vinculados a ela.

As chaves de teste (hm_test_…) foram desativadas em 12 de outubro de 2026. Elas respondem 401 test_keys_retired. Para testar uma entrega DDEX, use a mesma chave hm_live_ com POST /ddex/validate, ou a pasta SFTP /test. Nenhum dos dois cria nada. Veja Pasta de teste.

Crie uma chave

As chaves são criadas no app web da HILLS, na página Developers (/dashboard/developers), com New API key. Você precisa ser o proprietário da conta ou ter uma função na equipe com a permissão de chaves de API. A API vem com os planos Enterprise e Custom. Nos outros planos não é possível criar chaves, e as chaves existentes respondem 403 api_not_in_plan.

Para cada chave, você escolhe:

Um nome. Diga onde ela roda, por exemplo ERP sync ou website.
Escopos. O que a chave pode fazer. Veja abaixo.
Validade. Um número de dias, ou nenhuma.

A chave completa aparece uma única vez, quando você a cria. Depois disso, as listas mostram só o prefixo (por exemplo hm_live_ab12cd34). Se você a perder, crie uma nova.

Envie a chave

Envie-a como token Bearer:

curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"

const HILLS = "https://api.hillsmusic.com/v1";

export async function hills(path, init = {}) {
  const res = await fetch(HILLS + path, {
    ...init,
    headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
  });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error), { status: res.status, code: body.code });
  return body;
}

console.log(await hills("/me"));

GET /me e GET /ping funcionam com qualquer chave válida, sejam quais forem os escopos dela. Use-os para verificar uma chave. Veja Conta.

Escopos

Cada chave tem seus próprios escopos. Um endpoint que exige um escopo que a chave não tem responde 403 insufficient_scope, com o escopo que falta em scope.

Escopo	O que permite
`members:read`	Listar seus artistas e gravadoras.
`members:write`	Convidar novos artistas e gravadoras.
`catalog:read`	Lançamentos, faixas e a entrega deles às plataformas.
`earnings:read`	Receita por mês, lançamento ou plataforma.
`payouts:read`	Seu saldo e suas solicitações de saque.
`links:read`	Smartlinks e pré-saves com as estatísticas.
`ddex:write`	Entregar lotes DDEX ERN e ler o status deles. Também permite testes.
`ddex:validate`	Apenas testar lotes DDEX. Nada é criado.
`webhooks:read`	Listar endpoints de webhook e as entregas deles.
`webhooks:write`	Gerenciar endpoints de webhook, segredos, eventos de teste e novas tentativas.

As chaves novas começam com os cinco escopos de leitura: members:read, catalog:read, earnings:read, payouts:read e links:read. Os escopos de escrita, de DDEX e de webhook nunca vêm ativados por padrão.

Dê a cada sistema a sua própria chave, só com os escopos de que ele precisa. Uma rotina de relatórios precisa de earnings:read, não de ddex:write. Um job de CI que verifica arquivos DDEX precisa apenas de ddex:validate.

Rotação de chaves

As chaves não são rotacionadas no lugar. Para substituir uma sem indisponibilidade:

Crie uma nova chave com os mesmos escopos.
Implante-a no seu sistema.
Confirme que o tráfego migrou. A lista de chaves mostra quando cada uma foi usada pela última vez.
Revogue a chave antiga.

Revogue uma chave

Na página Developers, abra o menu da chave e escolha Revoke. Ela para de funcionar na hora e passa a responder 401 key_revoked. Revogue uma chave imediatamente se ela vazar, por exemplo se tiver sido commitada em um repositório ou colada em um chat.

Cada chave também tem um log de requisições. Selecione uma chave na lista para ver as requisições recentes: método, caminho, status e horário. As requisições ficam guardadas por 7 dias.

Erros de autenticação

Status	`code`	O que fazer
401	`unauthenticated`	Falta o header `Authorization: Bearer`. Adicione-o.
401	`invalid_key`	A chave não existe ou foi digitada errado. Procure espaços ou um valor cortado.
401	`key_revoked`	A chave foi revogada. Crie uma nova.
401	`key_expired`	A chave passou da validade. Crie uma nova.
401	`test_keys_retired`	Uma chave `hm_test_` antiga. Use uma chave `hm_live_`.
403	`insufficient_scope`	Falta à chave o escopo indicado em `scope`. Crie uma chave com ele.
403	`account_inactive`	Sua conta não está ativa. Fale com a HILLS Music.
403	`api_not_in_plan`	Seu plano não inclui a API. Ela vem com o Enterprise e o Custom.

Todos os erros têm o mesmo formato. Veja Erros.

Mantenha as chaves seguras

Guarde as chaves em um gerenciador de segredos ou em variáveis de ambiente, não no código.
Nunca coloque uma chave em uma página no navegador, em um app para celular ou em um app desktop. Qualquer pessoa consegue lê-la ali.
Use uma chave por sistema, para poder revogar uma sem parar as outras.
Defina uma validade nas chaves de projetos curtos e de prestadores de serviço.