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

# Autenticação

> Como obter suas credenciais, gerar o token Bearer e autenticar as requisições.

## Fluxo de autenticação

<Steps>
  <Step title="Obtenha suas credenciais">
    Crie suas credenciais na [Plataforma do RH](https://app.piposaude.com.br/) ou solicite para sua gerente de contas. Assim que a credencial é criada, você recebe um par de chaves: seu **Client ID** e um **Client Secret**. O Client Secret é mostrado somente uma vez, no momento da criação, então guarde em um local seguro. Caso perca o Client Secret, você poderá atualizar ou gerar um novo par.
  </Step>

  <Step title="Autentique-se com POST /v1/authenticate">
    A aplicação cliente faz o login no endpoint `POST /v1/authenticate` usando o par de chaves obtido no passo anterior.
  </Step>

  <Step title="Use o access-token nas chamadas">
    A resposta da requisição de autenticação contém o campo `access-token`. Esse é o token Bearer que a aplicação deve enviar no cabeçalho HTTP `Authorization` de toda chamada aos endpoints que exigem autenticação.
  </Step>
</Steps>

## Requisição

Envie o `client-id` e o `client-secret` no corpo da requisição, em JSON.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.piposaude.com.br/v1/authenticate \
    -H "Content-Type: application/json" \
    -d '{
      "client-id": "seu-id-aqui",
      "client-secret": "seu-secret-aqui"
    }'
  ```

  ```json Request body theme={null}
  {
    "client-id": "seu-id-aqui",
    "client-secret": "seu-secret-aqui"
  }
  ```
</CodeGroup>

<Callout icon="megaphone" color="#3370D1">
  Em Homologação, use a base URL `https://api.pipo.health`.
</Callout>

## Resposta

Autenticação bem sucedida (`200 OK`)

```json 200 OK theme={null}
{
  "access-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token-type": "bearer",
  "expires-in": 3600
}
```

## Usando o token nas demais chamadas

Envie o `access-token` no cabeçalho `Authorization`, prefixado por `Bearer`:

```bash theme={null}
curl https://api.piposaude.com.br/v1/company \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Erros

Se o par `client-id` + `client-secret` for inválido, a API retorna `403 Forbidden` com o erro `invalid-client`:

```json 403 Forbidden theme={null}
{
  "error": "invalid-client",
  "error-description": "Client authentication failed"
}
```

<Tip>
  Confira se está usando as credenciais do ambiente correto (Produção ou Homologação) e se o par Client ID + Client Secret foi copiado sem espaços extras.
</Tip>