Contexto da empresa (Multi-tenancy)

A API Maestron é multi-tenant: cada empresa cliente da Maestron é isolada das demais. Na API pública, esse isolamento é ainda mais direto do que no aplicativo — uma API Key pertence a exatamente uma empresa, e é essa empresa que a chave representa em toda chamada.

Resolução pela API Key

A empresa não é informada em nenhum campo ou header de requisição. Ela é resolvida a partir da própria chave usada no header Authorization:

Authorization: Bearer maestron_pk_9f1a3c7e2b8d4f6a0c5b9d3e7f1a4c8b6e2d0f9a

Consequências:

Não existe header de empresa. Qualquer campo desse tipo enviado no corpo ou na query é ignorado — não faz parte do contrato da API.
Uma chave nunca opera em mais de uma empresa. Para integrar duas empresas, são necessárias duas chaves, uma por empresa.
O mesmo endpoint retorna dados diferentes dependendo da chave usada, pois cada chave resolve a sua própria empresa.

Para como uma chave é gerada e autenticada, ver Autenticação.

Isolamento de dados

Listagens (GET de coleção) retornam apenas registros da empresa da chave. Não há vazamento entre empresas.
A busca por identificador (GET /{id}, PATCH, DELETE) só localiza recursos da empresa da chave. Um ID válido em outra empresa responde 404 — nunca 403 — para não revelar a existência do recurso fora do contexto da chave.
Operações de escrita afetam exclusivamente recursos da empresa da chave.
Uma chave nunca tem o bypass de “dono da empresa” que existe no aplicativo: mesmo criada pelo dono, ela só pode o que os escopos concedidos a ela permitem (ver Escopos & Permissões).

O detalhamento completo de cada código de status fica centralizado em Erros.