> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salvy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Chaves de API

> Crie e gerencie chaves de API de empresa e de organização para integrar seus sistemas com a Salvy

export const v_0 = "v3"

Toda requisição para a API da Salvy precisa de uma chave de API. Ela identifica sua empresa e autoriza o acesso aos recursos da plataforma.

## Acessando a página

Você pode criar, listar e revogar chaves a qualquer momento na página de API & Webhooks, disponível em Configurações > Funcionalidades, ou diretamente em app.salvy.com.br/settings/api.

## Criando uma chave

1. Acesse a página de [API & Webhooks](https://app.salvy.com.br/settings/api).
2. Clique em **Criar chave de API**.
3. Selecione o ambiente da chave (**Sandbox** ou **Produção**) no seletor exibido acima do campo de nome. Veja <a href={"/api-reference/" + v_0 + "/environments"}>Ambientes</a> para entender a diferença.
4. Dê um nome (opcional) à chave para identificá-la depois, por exemplo o sistema ou a finalidade em que ela será usada.
5. Clique em **Criar chave**.

<Warning>
  A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de
  fechar a janela.
</Warning>

Após copiar a chave, use-a no cabeçalho `Authorization` das suas requisições:

```
Authorization: Bearer <sua_chave>
```

Consulte a <a href={"/api-reference/" + v_0 + "/introduction"}>Introdução</a> para mais detalhes sobre autenticação.

## Revogando uma chave

Para revogar uma chave, clique no ícone de lixeira na coluna **Ações** e confirme a ação.

<Warning>
  A revogação é imediata e não pode ser desfeita. Qualquer sistema que esteja
  utilizando a chave deixará de acessar a API assim que a revogação for
  confirmada.
</Warning>

Chaves revogadas continuam visíveis na tabela com o status **Revogada**, junto com a data e o usuário responsável pela revogação, para fins de auditoria.

## Boas práticas

* Crie uma chave separada para cada sistema ou finalidade (como produção, homologação ou integrações diferentes). Isso facilita o rastreamento e a revogação quando necessário.
* A Salvy tem os ambientes **sandbox** e **produção**, definidos pela chave utilizada. Use chaves de sandbox para desenvolvimento e testes. Entenda a diferença em <a href={"/api-reference/" + v_0 + "/environments"}>Ambientes</a>.
* Nunca compartilhe chaves em repositórios públicos, e-mails ou mensagens. Armazene-as em um cofre de segredos.
* Revogue imediatamente qualquer chave que possa ter sido exposta e crie uma nova em seu lugar.
* Utilize nomes descritivos ao criar chaves para facilitar a identificação posterior.

## Chaves de organização

Chaves de organização autenticam como a sua **organização inteira**, e não como uma única empresa. Com uma chave de organização, uma mesma integração alcança **todas as empresas** da sua organização, sem precisar manter uma chave por empresa.

<Info>
  Chaves de organização funcionam apenas na **versão 3** da API (`/api/v3/`). Em
  versões anteriores, utilize chaves de empresa.
</Info>

### Chave de empresa ou de organização?

|                 | Chave de empresa                           | Chave de organização                                        |
| --------------- | ------------------------------------------ | ----------------------------------------------------------- |
| Abrangência     | Uma empresa                                | Todas as empresas da organização                            |
| Onde é criada   | Configurações da empresa (`/settings/api`) | Configurações da organização (`/organization/settings/api`) |
| Quem pode criar | Conforme a permissão de chaves de API      | Apenas administradores da organização                       |
| Prefixo         | `salvy_prod_`                              | `salvy_org_prod_`                                           |

Os endpoints passam a considerar todas as empresas da organização. Por exemplo, uma listagem retorna os recursos de todas as empresas de uma só vez — você não informa a empresa a cada requisição.

### Criando uma chave de organização

<Note>Apenas administradores da organização têm acesso a esta página.</Note>

1. Acesse [Configurações da organização > API](https://app.salvy.com.br/organization/settings/api).
2. Clique em **Criar chave de API**.
3. Dê um nome (opcional) à chave para identificá-la depois, por exemplo o sistema ou a finalidade em que ela será usada.
4. Selecione os escopos que a chave poderá utilizar.
5. Clique em **Criar chave**.

<Warning>
  A chave é exibida apenas uma vez. Copie e guarde-a em um local seguro antes de
  fechar a janela.
</Warning>

Chaves de organização são criadas no ambiente de **produção** (prefixo `salvy_org_prod_`). Use-a no cabeçalho `Authorization` das suas requisições:

```bash theme={null}
curl -X GET "https://api.salvy.com.br/api/v3/cost-centers" \
-H "Authorization: Bearer salvy_org_prod_sua_chave_aqui"
```

### Revogando uma chave

Para revogar uma chave, clique no ícone de lixeira na coluna **Ações** e confirme a ação.

<Warning>
  A revogação é imediata e não pode ser desfeita. Qualquer sistema que esteja
  utilizando a chave deixará de acessar a API assim que a revogação for
  confirmada.
</Warning>

Chaves revogadas continuam visíveis na tabela com o status **Revogada**, junto com a data e o usuário responsável pela revogação, para fins de auditoria.