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

# Aplicações OAuth (API)

> CRUD de apps OAuth, credenciais e autorizações via API key em /v1/oauth-apps/*

Gerencie **aplicações OAuth** pela API pública `/v1/oauth-apps/*` — mesmo padrão de [webhooks](/api-reference/endpoint/webhooks/list): `X-API-Key`, envelope JSON e rate limit global.

<Note>
  O **protocolo OAuth** (`/oauth/authorize`, `/oauth/token`) está no [guia OAuth 2.0](/api-reference/guides/oauth). Esta página cobre o **cadastro e gestão** de apps antes/depois do fluxo de autorização.
</Note>

## Autenticação

```http theme={null}
X-API-Key: gp_live_SUA_CHAVE
Content-Type: application/json
```

Respostas seguem o envelope padrão:

```json theme={null}
{
  "success": true,
  "message": "…",
  "data": { },
  "requestId": "req_abc"
}
```

Rate limit: **100 requisições/minuto** por API key (HTTP `429` ao exceder), igual às demais rotas `/v1/*`.

## Pré-requisitos

1. Conta com **API pública habilitada** (solicite ao suporte GoatPay se necessário).
2. Chave com permissões `oauth-apps/*` — tabela em [Permissões](/pages/guides/api-permissions#aplicações-oauth).
3. Para apps de terceiros consumirem `/v1/*`, após criar o app use o [fluxo OAuth](/api-reference/guides/oauth#fluxo-completo).

## Fluxo típico (dono da app)

<Steps>
  <Step title="1. Listar scopes">
    [GET /oauth-apps/scopes/list](/api-reference/endpoint/oauth-apps/scopes-list) — scopes permitidos no cadastro.
  </Step>

  <Step title="2. Criar app">
    [POST /oauth-apps/create](/api-reference/endpoint/oauth-apps/create) — nome, descrição e `allowedScopes`.
  </Step>

  <Step title="3. Credenciais DEV/PROD">
    [POST clients/ensure](/api-reference/endpoint/oauth-apps/clients-ensure) por ambiente; guarde o `clientSecret` (exibido uma vez).
  </Step>

  <Step title="4. Redirect URIs">
    [PUT redirect-uris](/api-reference/endpoint/oauth-apps/redirect-uris) — match exato no authorize.
  </Step>

  <Step title="5. Publicar fluxo OAuth">
    Redirecione usuários para [GET /oauth/authorize](/api-reference/endpoint/oauth/authorize) com PKCE.
  </Step>

  <Step title="6. Monitorar">
    [GET stats](/api-reference/endpoint/oauth-apps/stats) e [authorizations/list](/api-reference/endpoint/oauth-apps/authorizations-list).
  </Step>
</Steps>

## Papéis

| Papel                 | Quem é                                  | Rotas                                                                                 |
| --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------- |
| **Dono da aplicação** | Conta que registrou o app OAuth         | `list`, `create`, `get`, `update`, `delete`, `stats`, `authorizations/*`, `clients/*` |
| **Resource owner**    | Conta que autorizou um app de terceiros | `authorized-apps/list`, `authorized-apps/revoke`                                      |

## Referência de endpoints

### Dono da aplicação

| Método   | Rota                                                                  | Documentação                                                                     |
| -------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `GET`    | `/oauth-apps/scopes/list`                                             | [Scopes](/api-reference/endpoint/oauth-apps/scopes-list)                         |
| `GET`    | `/oauth-apps/list`                                                    | [Listar](/api-reference/endpoint/oauth-apps/list)                                |
| `POST`   | `/oauth-apps/create`                                                  | [Criar](/api-reference/endpoint/oauth-apps/create)                               |
| `GET`    | `/oauth-apps/get/{id}`                                                | [Consultar](/api-reference/endpoint/oauth-apps/get)                              |
| `PATCH`  | `/oauth-apps/update/{id}`                                             | [Atualizar](/api-reference/endpoint/oauth-apps/update)                           |
| `DELETE` | `/oauth-apps/delete/{id}`                                             | [Remover](/api-reference/endpoint/oauth-apps/delete)                             |
| `GET`    | `/oauth-apps/stats/{id}`                                              | [Estatísticas](/api-reference/endpoint/oauth-apps/stats)                         |
| `GET`    | `/oauth-apps/authorizations/list/{applicationId}`                     | [Autorizações](/api-reference/endpoint/oauth-apps/authorizations-list)           |
| `POST`   | `/oauth-apps/authorizations/revoke/{applicationId}/{authorizationId}` | [Revogar (dono)](/api-reference/endpoint/oauth-apps/authorization-revoke)        |
| `POST`   | `/oauth-apps/clients/ensure/{applicationId}/{environment}`            | [Gerar client](/api-reference/endpoint/oauth-apps/clients-ensure)                |
| `POST`   | `/oauth-apps/clients/regenerate-secret/{applicationId}/{environment}` | [Regenerar secret](/api-reference/endpoint/oauth-apps/clients-regenerate-secret) |
| `PUT`    | `/oauth-apps/clients/redirect-uris/{applicationId}/{environment}`     | [Redirect URIs](/api-reference/endpoint/oauth-apps/redirect-uris)                |

### Resource owner

| Método | Rota                                                   | Documentação                                                                |
| ------ | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| `GET`  | `/oauth-apps/authorized-apps/list`                     | [Apps conectados](/api-reference/endpoint/oauth-apps/authorized-apps-list)  |
| `POST` | `/oauth-apps/authorized-apps/revoke/{authorizationId}` | [Revogar acesso](/api-reference/endpoint/oauth-apps/authorized-apps-revoke) |

## Webhooks OAuth

Eventos `oauth.authorization.*`, `oauth.application.*` e `oauth.client.*` são entregues aos endpoints cadastrados na conta. Cadastre via `/v1/webhooks/*` com API key ou com bearer OAuth (`webhooks:write`). Detalhes no [guia de webhooks](/api-reference/guides/webhooks#oauth-20).

## Dashboard (alternativa)

O mesmo fluxo está disponível na UI: [Aplicações OAuth](https://app.goatpay.com.br/dashboard/integrations/developer) e [Conexões](https://app.goatpay.com.br/dashboard/account/connections#apps-oauth).

## Relacionado

* [Guia OAuth 2.0 (protocolo)](/api-reference/guides/oauth)
* [GET /v1/me](/api-reference/endpoint/account/me)
* [Rotas da API pública](/api-reference/escopo-api-publica)