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

# Autenticação

> Troque credenciais de cliente OAuth 2.0 por um token de acesso Bearer e chame a API MoneyDev.

A MoneyDev usa o fluxo OAuth 2.0 **client credentials** ([RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)). Você troca um client ID e um secret por um token de acesso de curta duração e envia esse token como credencial `Bearer` em toda requisição `/v1`.

<Warning>
  Seu client secret é uma credencial de servidor com acesso total à sua conta. Nunca coloque em código de navegador ou app mobile. Guarde em variável de ambiente e faça a rotação pelo [Dashboard](https://dashboard.moneydev.com.br) se ele vazar.
</Warning>

## Obtenha suas credenciais

Crie um cliente de API no [Dashboard](https://dashboard.moneydev.com.br), em **API Keys**. Você recebe:

* **`client_id`** — um identificador, seguro para registrar em log.
* **`client_secret`** — exibido uma única vez na criação. Guarde com segurança.

Cada cliente recebe um conjunto de [escopos](#escopos).

## Solicite um token de acesso

Faça um `POST` no endpoint de token com as credenciais em um header HTTP Basic e o corpo em formato `form-urlencoded`.

```bash cURL theme={null}
curl --request POST \
  --url https://api.moneydev.com.br/oauth/token \
  --user "$MONEYDEV_CLIENT_ID:$MONEYDEV_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials
```

```javascript Node.js theme={null}
const basic = Buffer.from(
  `${process.env.MONEYDEV_CLIENT_ID}:${process.env.MONEYDEV_CLIENT_SECRET}`,
).toString("base64");

const res = await fetch("https://api.moneydev.com.br/oauth/token", {
  method: "POST",
  headers: {
    Authorization: `Basic ${basic}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ grant_type: "client_credentials" }),
});

const { access_token, expires_in } = await res.json();
```

### Parâmetros

<ParamField body="grant_type" type="string" required>
  Deve ser `client_credentials`. É o único fluxo suportado.
</ParamField>

<ParamField body="scope" type="string">
  Lista de escopos separados por espaço. Omita para receber todos os escopos concedidos ao seu cliente. Pedir um escopo que o cliente não tem retorna `invalid_scope`.
</ParamField>

### Resposta

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "customers:read customers:write checkouts:write"
}
```

O token é um JWT assinado, válido por **`expires_in` segundos** (900 = 15 minutos). Guarde em cache e reutilize até perto de expirar; então solicite um novo — não há refresh token. O endpoint de token responde com `Cache-Control: no-store`.

## Chame a API

Envie o token como credencial `Bearer`:

```bash theme={null}
curl https://api.moneydev.com.br/v1/me \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

| Situação | Status | `error.code` |
| - | - | - |
| Sem header `Authorization: Bearer` | `401` | `missing_access_token` |
| Token inválido, expirado ou revogado | `401` | `invalid_access_token` |
| Token sem o escopo que o endpoint exige | `403` | `insufficient_scope` |

## Escopos

| Escopo | Permite |
| - | - |
| `customers:read` | Ler clientes |
| `customers:write` | Criar clientes |
| `products:read` | Ler produtos e ofertas |
| `products:write` | Criar e atualizar produtos e ofertas |
| `checkouts:read` | Ler sessões de checkout |
| `checkouts:write` | Criar sessões de checkout |
| `all` | Todos os escopos acima |

Cada página de endpoint indica o escopo que ela exige. Ofertas são cobertas pelos escopos `products:*`.

## Erros do endpoint de token

Os erros de `/oauth/token` seguem o formato da spec OAuth — `{ "error": "...", "error_description": "..." }` — e não o [objeto de erro padrão da API](/api-reference/errors).

| `error` | Status | Causa |
| - | - | - |
| `invalid_request` | `400` | O corpo não era `application/x-www-form-urlencoded` |
| `unsupported_grant_type` | `400` | `grant_type` não era `client_credentials` |
| `invalid_client` | `401` | Credenciais de cliente ausentes ou incorretas |
| `invalid_scope` | `400` | Pediu um escopo que o cliente não tem |
| `temporarily_unavailable` | `503` | O servidor de autorização não conseguiu emitir o token |

## Discovery

Endpoints de metadados padrão permitem que ferramentas OAuth se configurem sozinhas:

* `GET /.well-known/oauth-authorization-server` — issuer, endpoint de token, fluxos e escopos suportados.
* `GET /.well-known/jwks.json` — as chaves públicas que assinam os tokens de acesso (`RS256`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.