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

# Moove API Keys

> Crie uma chave API com âmbito limitado para a Moove API, copie-a uma vez e revogue-a definitivamente quando terminar.

Crie uma chave, copie-a uma vez, use-a para chamar a Moove API.

<Info>
  **Apenas na web**, em [moove.xyz/dashboard/api-keys](https://www.moove.xyz/dashboard/api-keys). Não há equivalente no telemóvel.
</Info>

## Como crio uma chave API?

<Steps>
  <Step title="Abra Gerir → Chaves API">
    No painel web.
  </Step>

  <Step title="Dê-lhe um nome">
    Algo que reconheça daqui a seis meses — o serviço ou o ambiente a que se destina.
  </Step>

  <Step title="Escolha um agente">
    O **Moove Receive Agent** é o que existe. Expande-se para os âmbitos de que esse agente precisa.
  </Step>

  <Step title="Copie a chave">
    <Warning>
      A chave em texto simples é mostrada **uma única vez**, no momento da criação. Copie-a agora e guarde-a no seu gestor de segredos. Se fechar a janela sem a copiar, a chave fica inutilizável — crie outra.
    </Warning>
  </Step>
</Steps>

O URL base é `https://api.moove.xyz`.

## Moove Agents, não âmbitos em bruto

Escolhe um **agente**, não uma cadeia de permissões. "Moove Receive Agent" é a unidade sobre a qual um comerciante consegue raciocinar; `payment_link:create` não é.

| Agente                  | Estado    | Âmbitos que concede                        |
| ----------------------- | --------- | ------------------------------------------ |
| **Moove Receive Agent** | **Ativo** | `payment_link:create`, `payment_link:read` |
| Moove Send Agent        | Em breve  | —                                          |
| Moove Swap Agent        | Em breve  | —                                          |
| Moove Ramp Agent        | Em breve  | —                                          |

Os três agentes que estão para breve aparecem desativados. Selecionar um deles criaria uma chave que não concede nada, por isso o seletor não o permite.

## O que uma chave API pode e não pode fazer

<Note>
  Uma chave é um **âmbito reduzido de si**. Atua como a sua conta e só pode fazer um subconjunto do que você pode fazer.

  **Nenhum endpoint move fundos.** Um link de pagamento liquida sempre na sua própria carteira predefinida, no token dessa carteira — quem chama não pode indicar um destino. Uma chave divulgada pode criar pedidos que *lhe* pagam a si. Não pode pagar a mais ninguém.
</Note>

Uma chave também não pode criar outra chave. A gestão de chaves é autenticada apenas por sessão, por isso uma chave comprometida não se consegue escalar a si própria.

## Como mantenho uma chave segura?

<Warning>
  * Guarde-a num gestor de segredos ou numa variável de ambiente. Nunca no controlo de versões.
  * Nunca a cole num prompt, numa conversa, num issue ou numa captura de ecrã.
  * Use uma chave separada por serviço, para que revogar uma não deite abaixo as restantes.
  * Revogue qualquer chave sobre a qual tenha dúvidas. Criar uma nova demora segundos.
</Warning>

## Quantas chaves posso ter?

Até **10 chaves ativas** por conta. Se criar uma décima primeira, o pedido é recusado com `TOO_MANY_API_KEYS` — revogue primeiro uma que já não use.

<Tip>
  Esse limite é uma razão para dar âmbito às chaves por integração e não por implantação. Uma chave por serviço que efetivamente corre é mais fácil de compreender, e mais fácil de revogar quando algo muda.
</Tip>

## Como revogo uma chave?

<Steps>
  <Step title="Abra o menu da chave">
    Em **Gerir → Chaves API**, abra o menu **…** na linha da chave e escolha **Revogar**.
  </Step>

  <Step title="Confirme">
    Clique novamente em **Revogar** para confirmar. A chave deixa de funcionar de imediato.
  </Step>
</Steps>

<Warning>
  **A revogação é definitiva.** Não há forma de a desfazer. O texto simples nunca foi guardado, por isso uma chave revogada nunca poderia voltar a ser usada, mesmo que o registo fosse restaurado. Emita antes uma chave nova.
</Warning>

## Como uso uma chave?

Envie-a no cabeçalho `X-API-Key` em todos os pedidos.

```bash theme={null}
curl -sS -X POST "https://api.moove.xyz/v1/payment-link" \
  -H "X-API-Key: $MOOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toAmount": "49.99" }'
```

[Autenticação →](/api-reference/authentication)

## Antes da sua primeira chamada

A API recusa-se a criar links para uma conta que não pode receber pagamentos. Certifique-se de que reservou um [Moove Handle](/pt-pt/brand/moove-handle) e definiu uma carteira predefinida com um [token de liquidação](/pt-pt/concepts/settlement-and-auto-routing) — caso contrário receberá um `409`.

## O que ler a seguir

<CardGroup cols={3}>
  <Card title="Autenticação" icon="lock" href="/api-reference/authentication">
    Como funciona o cabeçalho.
  </Card>

  <Card title="Pagamentos Agênticos Moove" icon="sparkles" href="/pt-pt/transact/moove-agentic-payments">
    Deixe uma ferramenta de IA fazer a integração.
  </Card>

  <Card title="API dos Moove Payment Links" icon="link" href="/api-reference/moove-receive/moove-payment-links">
    Os endpoints por inteiro.
  </Card>
</CardGroup>

Com âmbito limitado, revogável, sua. O seu dinheiro. O seu movimento.