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

# Registrar um cliente OAuth MCP

> Registre um cliente público com URLs exatas de callback e um conjunto limitado de permissões do produto.

Registre um cliente público com URLs exatas de callback e um conjunto limitado de permissões do produto.

```http theme={null}
POST https://api.voicecheap.ai/oauth/register
```

## Autenticação

Nenhuma. O registro não faz login de um usuário nem autoriza uma conexão de conta.

## Corpo da requisição

<ParamField body="redirect_uris" type="array" required>
  Entre 1 e 10 callbacks antes da remoção de duplicatas.

  Mínimo de itens: 1. Máximo de itens: 10.
</ParamField>

<ParamField body="client_name" type="string">
  Rótulo opcional do cliente; os espaços nas extremidades são removidos antes de salvar e ele deve continuar não vazio.

  Comprimento mínimo: 1. Comprimento máximo: 120. Padrão: `^(?=.*\S)[^\u0000-\u001F\u007F]+$`. Valor padrão: "MCP client".
</ParamField>

<ParamField body="token_endpoint_auth_method" type="field">
  Somente clientes públicos.

  Valor obrigatório: "none". Valor padrão: "none".
</ParamField>

<ParamField body="grant_types" type="union">
  Deve incluir authorization\_code; refresh\_token é opcional. A omissão ou null seleciona ambos. Valores duplicados são removidos.

  Valor padrão: \["authorization\_code","refresh\_token"].
</ParamField>

<ParamField body="response_types" type="array">
  Lista de valores. Consulte o esquema de entrada completo para ver a estrutura dos itens.

  Mínimo de itens: 1. Máximo de itens: 1. Valor padrão: \["code"].
</ParamField>

<ParamField body="scope" type="string">
  Permissões de scopes\_supported separadas por espaços, podendo incluir offline\_access. Nomes não suportados e valores contendo apenas espaços em branco são rejeitados; duplicatas são removidas. Omitir scope ou não indicar permissões de produto, como apenas openid ou apenas offline\_access, registra todos os escopos de produto suportados. email exige openid; email sozinho é rejeitado. Quando OpenID Connect está disponível, o registro inclui openid e email como capacidades do cliente mesmo se scope for omitido. O registro não concede acesso; permissões de identidade exigem uma solicitação de autorização explícita e o consentimento do usuário.

  Comprimento mínimo: 1. Comprimento máximo: 2048. Padrão: `^ *(?:account:read|usage:read|settings:read|settings:write|team:read|team:write|projects:read|projects:write|projects:delete|translations:write|transcription:read|transcription:write|subtitles:read|subtitles:write|tts:read|tts:write|voices:read|voices:write|images:read|images:write|thumbnails:read|thumbnails:write|folders:read|folders:write|glossary:read|glossary:write|webhooks:read|webhooks:write|publishing:read|publishing:write|offline_access|openid|email)(?: +(?:account:read|usage:read|settings:read|settings:write|team:read|team:write|projects:read|projects:write|projects:delete|translations:write|transcription:read|transcription:write|subtitles:read|subtitles:write|tts:read|tts:write|voices:read|voices:write|images:read|images:write|thumbnails:read|thumbnails:write|folders:read|folders:write|glossary:read|glossary:write|webhooks:read|webhooks:write|publishing:read|publishing:write|offline_access|openid|email))* *$`.
</ParamField>

<Accordion title="Esquema técnico">
  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "redirect_uris": {
        "type": "array",
        "minItems": 1,
        "maxItems": 10,
        "items": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2048,
          "pattern": "^[^\\s\\u0000-\\u001F\\u007F-\\u009F#\\\\]+$",
          "format": "uri",
          "anyOf": [
            {
              "pattern": "^[Hh][Tt][Tt][Pp][Ss]://"
            },
            {
              "pattern": "^http://(?:localhost|127\\.0\\.0\\.1|\\[::1\\])(?::[0-9]{1,5})?(?:/|\\?|$)"
            },
            {
              "const": "cursor://anysphere.cursor-mcp/oauth/callback"
            }
          ],
          "description": "An absolute HTTPS callback, an HTTP callback using the exact lowercase loopback spelling localhost, 127.0.0.1, or [::1], or exactly cursor://anysphere.cursor-mcp/oauth/callback. Must parse as a URL with no username/password, whitespace, control characters, backslashes, or fragment. A loopback port must be a valid URL port. The exact spelling is retained."
        },
        "description": "Between 1 and 10 callbacks before duplicates are removed."
      },
      "client_name": {
        "type": "string",
        "minLength": 1,
        "maxLength": 120,
        "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$",
        "default": "MCP client",
        "description": "Optional client label; trimmed before saving and must remain nonempty."
      },
      "token_endpoint_auth_method": {
        "const": "none",
        "default": "none",
        "description": "Public clients only."
      },
      "grant_types": {
        "anyOf": [
          {
            "type": "array",
            "minItems": 1,
            "items": {
              "enum": [
                "authorization_code",
                "refresh_token"
              ]
            },
            "contains": {
              "const": "authorization_code"
            }
          },
          {
            "type": "null"
          }
        ],
        "default": [
          "authorization_code",
          "refresh_token"
        ],
        "description": "Must include authorization_code; refresh_token is optional. Omitted or null selects both. Duplicate values are removed."
      },
      "response_types": {
        "type": "array",
        "minItems": 1,
        "maxItems": 1,
        "items": {
          "const": "code"
        },
        "default": [
          "code"
        ]
      },
      "scope": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2048,
        "pattern": "^ *(?:account:read|usage:read|settings:read|settings:write|team:read|team:write|projects:read|projects:write|projects:delete|translations:write|transcription:read|transcription:write|subtitles:read|subtitles:write|tts:read|tts:write|voices:read|voices:write|images:read|images:write|thumbnails:read|thumbnails:write|folders:read|folders:write|glossary:read|glossary:write|webhooks:read|webhooks:write|publishing:read|publishing:write|offline_access|openid|email)(?: +(?:account:read|usage:read|settings:read|settings:write|team:read|team:write|projects:read|projects:write|projects:delete|translations:write|transcription:read|transcription:write|subtitles:read|subtitles:write|tts:read|tts:write|voices:read|voices:write|images:read|images:write|thumbnails:read|thumbnails:write|folders:read|folders:write|glossary:read|glossary:write|webhooks:read|webhooks:write|publishing:read|publishing:write|offline_access|openid|email))* *$",
        "description": "Space-delimited permissions from scopes_supported, optionally including offline_access. Unsupported names and whitespace-only values are rejected; duplicates are removed. Omitting scope or supplying no product scopes, such as openid alone or offline_access alone, registers all supported product scopes. email requires openid; email alone is rejected. When OpenID Connect is available, registration includes openid and email as client capabilities even when scope is omitted. Registration grants no access; identity permissions require an explicit authorization request and user consent.",
        "examples": [
          "account:read projects:read offline_access"
        ]
      }
    },
    "required": [
      "redirect_uris"
    ],
    "additionalProperties": true
  }
  ```
</Accordion>

## Exemplos de requisição

Siga a codificação e a autenticação documentadas para esta rota. O formato de resposta e as regras de idempotência da API de ações se aplicam apenas às chamadas de ações.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/oauth/register' \
    --header 'Content-Type: application/json' \
    --data '{"client_name":"Acme assistant","redirect_uris":["https://assistant.example.com/oauth/callback"],"token_endpoint_auth_method":"none","grant_types":["authorization_code","refresh_token"],"response_types":["code"],"scope":"account:read projects:read offline_access"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    client_name: 'Acme assistant',
    redirect_uris: ['https://assistant.example.com/oauth/callback'],
    token_endpoint_auth_method: 'none',
    grant_types: ['authorization_code', 'refresh_token'],
    response_types: ['code'],
    scope: 'account:read projects:read offline_access',
  };
  const response = await fetch('https://api.voicecheap.ai/oauth/register', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
    redirect: 'manual',
  });
  console.log(response.status, await response.text());
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.request(
      "POST",
      "https://api.voicecheap.ai/oauth/register",
      headers={"Content-Type":"application/json"},
      json={"client_name": "Acme assistant", "redirect_uris": ["https://assistant.example.com/oauth/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "account:read projects:read offline_access"},
      timeout=120,
      allow_redirects=False,
  )
  print(response.status_code, response.text)
  ```
</RequestExample>

## Resposta

Metadados do cliente público registrado. Salve client\_id e use-o com o redirect\_uri exato registrado. Nenhum client\_secret é emitido.

```json HTTP 201 theme={null}
{
  "client_id": "mcp_client_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "client_id_issued_at": 1792152000,
  "client_name": "Acme assistant",
  "redirect_uris": ["https://assistant.example.com/oauth/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "account:read projects:read offline_access"
}
```

## Cabeçalhos da resposta

```json theme={null}
{
  "Cache-Control": "no-store",
  "Pragma": "no-cache"
}
```

## Notas da operação

* Parâmetros escalares reconhecidos devem ser fornecidos uma única vez como strings não vazias, sem caracteres de controle ASCII ou DEL. Campos de consulta/formulário repetidos são decodificados como arrays e rejeitados quando lidos como escalares.
* Use Content-Type application/json. Um corpo de registro codificado em URL é rejeitado com a resposta OAuth invalid\_request; tipos de mídia incompatíveis podem ser rejeitados antes pelo parser da integração.
* As URIs de redirecionamento são mantidas e comparadas exatamente. Alterações de maiúsculas e minúsculas, representação da porta, caminho, consulta ou barra final exigem o registro dessa URI exata.
* Callbacks HTTP aceitam apenas os nomes de loopback literais localhost, 127.0.0.1 e \[::1]. Hosts de redes privadas, grafias alternativas de IP, \*.localhost e LOCALHOST em maiúsculas não se qualificam.
* O único callback com esquema URI personalizado aceito é exatamente cursor://anysphere.cursor-mcp/oauth/callback.
* Todos os callbacks devem passar pela validação; um callback inválido rejeita todo o registro. Credenciais na URL, espaços em branco, caracteres de controle, fragmentos e barras invertidas são rejeitados.
* O cliente pode registrar qualquer escopo de produto compatível, mas o usuário deve aprovar separadamente o subconjunto solicitado durante a autorização. O registro por si só não concede acesso.
* Somente as concessões authorization\_code e, opcionalmente, refresh\_token são compatíveis. Um cliente registrado sem refresh\_token não recebe refresh token.
* Campos de metadados desconhecidos no nível superior são ignorados pela implementação atual. Os campos conhecidos mantêm as restrições mostradas no esquema.
* O limite público de registro é de 10 requisições por 10 minutos por IP de cliente, compartilhado entre workers. Corpos JSON são limitados a 1 MiB.
* Um registro bem-sucedido retorna HTTP 201.
* openid e email são permissões de identidade, separadas das permissões do produto, aceitas apenas quando anunciadas. email exige openid. Na autorização inicial, uma solicitação apenas com escopos de identidade usa as permissões padrão do produto mostradas na tela de consentimento.

## Erros

| Status HTTP | Código | Significado ou recuperação |
| - | - | - |
| 400 | `invalid_request` | O corpo ou um parâmetro reconhecido é inválido, está ausente, está duplicado ou tem a codificação errada. |
| 400 | `invalid_client_metadata` | Número de callbacks inválido, rótulo do cliente vazio, autenticação de cliente, tipos de concessão ou tipos de resposta não compatíveis. |
| 400 | `invalid_redirect_uri` | Uma URL de callback usa um formato incompatível ou inseguro. |
| 400 | `invalid_scope` | A string scope contém uma permissão não compatível ou não contém escopos solicitados. |
| 413 | `REQUEST_TOO_LARGE` | A requisição excede o tamanho permitido do corpo. JSON é limitado a 1 MiB e formulários codificados em URL a 32 KiB. |
| 415 | `UNSUPPORTED_CONTENT_TYPE` | O parser de corpo da integração aceita apenas JSON ou formulários codificados em URL. A rota pode exigir especificamente uma dessas codificações. |
| 429 | `temporarily_unavailable` | O limite de requisições OAuth públicas foi atingido. Aguarde a janela atual antes de tentar novamente. |
| 500 | `server_error` | A autorização está temporariamente indisponível. Tente novamente mais tarde. |


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