> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.gomoney.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.gomoney.me/_mcp/server.

# Autenticação da API

## O que precisa existir antes do primeiro login

Para usar a API, o usuário responsável pela integração precisa:

1. criar um acesso na plataforma, na área de acessos;
2. definir esse acesso como tipo `INTEGRATION`;
3. manter a permissão `INTEGRATION_ONLY` ativa nesse acesso;
4. solicitar ao suporte, por e-mail, as credenciais `clientKey` e `clientSecret`;
5. informar ao suporte o domínio que fará as chamadas da integração;
6. ter uma wallet cadastrada e aprovada para direcionamento dos recebimentos PIX em GMC.

O login da API deve ser feito com o `email` e a `senha` desse acesso de integração, não com o usuário principal da conta.

## Login na API PIX

```http
POST https://api-pix.gomoney.me/auth/login
Content-Type: application/json
```

```json
{
  "email": "{{userEmail}}",
  "password": "{{userPassword}}"
}
```

Resposta esperada:

```json
{
  "token": "pix-jwt-token",
  "title": "Successfull login.",
  "expiresIn": 1783191600000,
  "userId": "66f0b1b5c1f7b7dc0ce20001"
}
```

## Credenciais usadas no fluxo

* `accessToken`: token retornado no login da API PIX com o acesso `INTEGRATION_ONLY`;
* `clientKey` e `clientSecret`: credenciais entregues pelo suporte por e-mail;
* `Origin`: domínio previamente informado ao suporte;
* wallet aprovada: wallet operacional cadastrada para o direcionamento dos recebimentos PIX em GMC.

## Montagem da `secret-key`

Formato exigido:

```text
btoa(clientKey:clientSecret)
```

Exemplo de uso em header:

```http
Authorization: Bearer {{accessToken}}
secret-key: {{secretKeyBase64}}
```

## Regras de validação

* o `email` e a `senha` usados no login precisam pertencer a um acesso do tipo `INTEGRATION`;
* esse acesso precisa estar ativo e com a permissão `INTEGRATION_ONLY`;
* a `secret-key` precisa ser montada com o `clientKey` e o `clientSecret` enviados pelo suporte;
* o domínio enviado no header `Origin` precisa corresponder ao domínio aprovado pelo suporte;
* o token `Bearer` e a `secret-key` precisam representar o mesmo usuário de integração.

## Códigos de retorno mais comuns

| Endpoint      | Código | Significado                                                    |
| ------------- | ------ | -------------------------------------------------------------- |
| `/auth/login` | `201`  | Login da API PIX realizado com sucesso.                        |
| `/auth/login` | `401`  | Credenciais inválidas ou acesso sem liberação para integração. |
| `/auth/login` | `429`  | Usuário bloqueado temporariamente por excesso de tentativas.   |

## Erros comuns

* tentativa de login com usuário principal em vez do acesso de integração;
* acesso sem `INTEGRATION_ONLY` ativo;
* `clientKey` e `clientSecret` divergentes do usuário autenticado;
* domínio diferente do que foi liberado pelo suporte;
* wallet operacional ainda não aprovada para o fluxo de recebimento PIX em GMC.