Try It! permite que os desenvolvedores acreitem suas solicitações diretamente no console, usando o esquema de segurança que sua API definir. O Document360 lê a configuração de autenticação da sua especificação OpenAPI e apresenta os campos corretos para cada método, para que os desenvolvedores possam fornecer credenciais e enviar uma solicitação autorizada sem deixar a documentação.
Este artigo explica como escolher um método de autenticação no console, como cada método suportado funciona e como configurar sua especificação OpenAPI para que o método apareça corretamente no Try It!. Para uma visão geral do console, veja Testando endpoints com Teste!.
Escolhendo um método de autenticação
Quando um endpoint define um ou mais esquemas de segurança, o console Try It! mostra uma aba de Autorização . No topo dessa aba há um seletor de métodos de Autenticação listando todos os esquemas que o endpoint suporta.
Selecione um método, e o console exibe os campos de credenciais para esse esquema. Se um endpoint suporta mais de um método, os desenvolvedores podem escolher o que quiserem para autenticar.
O Document360 suporta os seguintes métodos de autenticação:
| Método | Como funciona |
|---|---|
| Chave API | Uma chave única era passada nos cabeçalhos de requisição. |
| Autenticação básica | Um nome de usuário e senha eram passados no cabeçalho da solicitação. |
| Token de portador | Um token gerado após o login, passado pelo cabeçalho de Autorização. |
| OAuth 2.0 | Autorização delegada por meio de um fluxo de login, com suporte para PKCE. |
| OpenID Connect | Estende o OAuth 2.0 para adicionar verificação de identidade de usuário. |
Os métodos de autenticação são definidos na sua especificação OpenAPI sob components/securitySchemes e aplicados a endpoints individuais usando o security campo.
O Try It! suporta múltiplos esquemas de segurança simultaneamente, para que os desenvolvedores possam testar endpoints que exigem mais de um método de autenticação na mesma sessão.
Chave API
A autenticação por chave API utiliza uma chave única passada nos cabeçalhos das requisições.
Na sua especificação OpenAPI:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
Aplique isso a um endpoint:
/your-endpoint:
get:
security:
- ApiKeyAuth: []
No console, selecione a chave API como método de autenticação. O campo Nome é fixo ao nome do cabeçalho definido na sua especificação (X-API-Key no exemplo acima), e os desenvolvedores inserem sua chave no campo Valor . A chave é então enviada nesse cabeçalho junto com a solicitação.
Autenticação básica
A autenticação básica requer um nome de usuário e senha codificados e passados no Authorization cabeçalho de cada solicitação.
Na sua especificação OpenAPI:
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
Aplique isso a um endpoint:
/your-endpoint:
get:
security:
- basicAuth: []
No console, selecione Autenticação Básica e insira o nome de usuário e a senha. Try It! codifica e envia no Authorization cabeçalho quando a solicitação é enviada.
Token de portador
A autenticação do token portador usa um token passado no Authorization cabeçalho como Bearer <token>.
Na sua especificação OpenAPI:
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
O Document360 exige que o esquema de segurança seja nomeado BearerAuth (sensível a maiúsculas e minúsculas). Se essa definição estiver ausente na sua especificação, clicar em Experimentar! em um endpoint afetado retornará um erro 403. Durante a importação, o Document360 sinalizará isso na seção de Alertas se detectar uma definição de BearerAuth faltante.
Aplique isso a um endpoint:
/your-endpoint:
get:
security:
- BearerAuth: []
No console, selecione o token de portador e insira o token. Tente! envia no Authorization cabeçalho como Bearer <token>.
OAuth 2.0
O OAuth 2.0 permite que os desenvolvedores autorizem por meio de um fluxo de login, em vez de inserir uma credencial estática. O Document360 suporta os seguintes fluxos — use aquele que corresponde à forma como sua API emite os tokens de acesso.
| Fluxo | Quando usá-lo |
|---|---|
| Código de Autorização | Aplicações do lado do servidor onde o segredo do cliente pode ser mantido confidencial. |
| PKCE | Clientes públicos, como aplicativos de página única e aplicativos móveis, onde o segredo não pode ser mantido confidencial. |
| Credenciais do Cliente | Comunicação máquina a máquina onde nenhum usuário está envolvido. |
| Implícito | Fluxo legado. Não recomendado para novas implementações. |
Loginando
Quando um desenvolvedor seleciona OAuth 2.0 no console, ele vê a configuração do esquema e uma lista de escopos, seguida de um botão Autorizar . Os escopos definidos para o esquema são pré-selecionados; Os desenvolvedores podem eliminar qualquer coisa que não precisarem antes de autorizar.
Clicar em Autorizar inicia o fluxo de login. Quando a API usa PKCE, não é necessária configuração manual no console — o Try It! gerencia a troca automaticamente, e o desenvolvedor só precisa fazer login. Uma vez concluída a autorização, o console usa o token de acesso resultante para as requisições a esse endpoint.
Exemplo de definição de especificação (Fluxo de código de autorização)
components:
securitySchemes:
oauth2Auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.yourdomain.com/oauth/authorize
tokenUrl: https://auth.yourdomain.com/oauth/token
scopes:
read: Read access
write: Write access
Para o comportamento de redirecionamento de URI e atualização de token que o OAuth 2.0 exige, veja Configurando seu provedor OAuth abaixo.
OpenID Connect
O OpenID Connect estende o OAuth 2.0 adicionando verificação de identidade do usuário. Ele está configurado de forma semelhante ao OAuth 2.0 e possui os mesmos requisitos de URI de redirecionamento e renovação silenciosa.
Na sua especificação OpenAPI:
components:
securitySchemes:
openIdConnect:
type: openIdConnect
openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration
No console, selecione OpenID Connect e complete o fluxo de login. Assim como no OAuth 2.0, veja Configurando seu provedor OAuth abaixo para as configurações necessárias do provedor.
Configurando seu provedor OAuth
Tanto o OAuth 2.0 quanto o OpenID Connect exigem duas configurações para que a autorização funcione corretamente no Try It!.
URI de redirecionamento — Após o desenvolvedor concluir o fluxo de autorização, o provedor o redireciona de volta para a referência da API. Adicione a URL de retorno de chamada OAuth da referência da API à lista de URIs de redirecionamento permitidos do seu provedor OAuth:
https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html
Substitua <your-knowledge-base-domain> pelo domínio onde sua documentação da API foi publicada.
Renovação silenciosa — O Document360 atualiza automaticamente o token de acesso em segundo plano enquanto o desenvolvedor está usando ativamente o Try It!, para que a sessão não expire no meio do uso. Não é necessária nenhuma configuração do seu lado; Isso é tratado automaticamente.
Aplicando múltiplos esquemas de segurança a um único endpoint
Se um endpoint requer mais de um método de autenticação simultaneamente, defina-os juntos sob security o nível operacional:
/secure-endpoint:
get:
security:
- BearerAuth: []
ApiKeyAuth: []
Isso exige que tanto um token Portador quanto uma chave API sejam fornecidos antes que a solicitação possa ser enviada. O Try It! suporta múltiplos esquemas de segurança em uma única sessão, para que os desenvolvedores possam fornecer credenciais para cada um e enviar uma solicitação autorizada.
Sessões e segurança
- As credenciais são apenas para a sessão. As credenciais inseridas pelo desenvolvedor são mantidas apenas para a sessão ativa e não são salvas. Quando a sessão termina, eles devem ser inseridos novamente.
- As credenciais são mascaradas na prévia do pedido. Valores sensíveis são ocultos na pré-visualização da Solicitação para que não fiquem expostos na tela durante a construção de uma solicitação.
FAQ
Onde os desenvolvedores inserem credenciais no console?
Na aba Autorização do console Experimente!. Selecione o método de autenticação, e o console mostra os campos de credenciais para esse esquema.
Por que um endpoint retorna um erro 403 quando clico em Tentar!?
Para autenticação de token portador, o Document360 exige que o esquema de segurança seja nomeado BearerAuth (sensível a maiúsculas e minúsculas). Se essa definição estiver ausente da sua especificação, os endpoints afetados retornam um erro 403.
Preciso configurar algo para OAuth 2.0 com PKCE?
Quando sua API usa PKCE, não é necessária configuração manual no console — os desenvolvedores só precisam clicar em Autorizar e fazer login. Você ainda precisa adicionar o URI de redirecionamento da referência da API à lista de permitidos do seu provedor OAuth. Veja Configurando seu provedor OAuth.
As credenciais que eu inserir são guardadas para a próxima vez?
Não. As credenciais são mantidas apenas para a sessão ativa e não são mantidas por persistência. Eles também estão mascarados na prévia de solicitação para segurança.