Authorizing requests in the Try It! console

Try It! lets developers authenticate their requests directly in the console, using whichever security scheme your API defines. Document360 reads the authentication configuration from your OpenAPI specification and surfaces the right fields for each method, so developers can supply credentials and send an authorized request without leaving the documentation.

This article explains how to choose an authentication method in the console, how each supported method works, and how to configure your OpenAPI specification so the method appears correctly in Try It!. For a general overview of the console, see Testing endpoints with Try it!.

Choosing an authentication method

When an endpoint defines one or more security schemes, the Try It! console shows an Authorization tab. At the top of that tab is an Authentication method selector listing every scheme the endpoint supports.

Select a method, and the console displays the credential fields for that scheme. If an endpoint supports more than one method, developers can pick whichever one they want to authenticate with.

Document360 supports the following authentication methods:

Authentication methods are defined in your OpenAPI specification under components/securitySchemes and applied to individual endpoints using the security field.

API key

API key authentication uses a unique key passed in the request headers.

In your OpenAPI spec:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Apply it to an endpoint:

/your-endpoint:
  get:
    security:
      - ApiKeyAuth: []

In the console, select API key as the authentication method. The Name field is fixed to the header name defined in your spec (X-API-Key in the example above), and developers enter their key in the Value field. The key is then sent in that header with the request.

Basic authentication

Basic authentication requires a username and password encoded and passed in the Authorization header of each request.

In your OpenAPI spec:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Apply it to an endpoint:

/your-endpoint:
  get:
    security:
      - basicAuth: []

In the console, select Basic authentication and enter the username and password. Try It! encodes them and sends them in the Authorization header when the request is sent.

Bearer token

Bearer token authentication uses a token passed in the Authorization header as Bearer <token>.

In your OpenAPI spec:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Apply it to an endpoint:

/your-endpoint:
  get:
    security:
      - BearerAuth: []

In the console, select Bearer token and enter the token. Try It! sends it in the Authorization header as Bearer <token>.

OAuth 2.0

OAuth 2.0 lets developers authorize through a sign-in flow rather than entering a static credential. Document360 supports the following flows — use the one that matches how your API issues access tokens.

Signing in

When a developer selects OAuth 2.0 in the console, they see the scheme's configuration and a list of scopes, followed by an Authorize button. The scopes defined for the scheme are pre-selected; developers can clear any they do not need before authorizing.

Clicking Authorize starts the sign-in flow. When the API uses PKCE, no manual configuration is needed in the console — Try It! handles the exchange automatically, and the developer only needs to sign in. Once authorization completes, the console uses the resulting access token for requests to that endpoint.

Example spec definition (Authorization Code flow)

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

For the redirect URI and token-refresh behaviour that OAuth 2.0 requires, see Configuring your OAuth provider below.

OpenID Connect

OpenID Connect extends OAuth 2.0 by adding user identity verification. It is configured similarly to OAuth 2.0 and has the same redirect URI and silent renewal requirements.

In your OpenAPI spec:

components:
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration

In the console, select OpenID Connect and complete the sign-in flow. As with OAuth 2.0, see Configuring your OAuth provider below for the required provider settings.

Configuring your OAuth provider

Both OAuth 2.0 and OpenID Connect require two settings so that authorization works correctly in Try It!.

Redirect URI — After a developer completes the authorization flow, the provider redirects them back to the API reference. Add the API reference's OAuth callback URL to your OAuth provider's list of allowed redirect URIs:

https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html

Replace <your-knowledge-base-domain> with the domain your API documentation is published on.

Silent renewal — Document360 automatically refreshes the access token in the background while a developer is actively using Try It!, so the session does not expire mid-use. No configuration is required on your end; this is handled automatically.

Applying multiple security schemes to one endpoint

If an endpoint requires more than one authentication method simultaneously, define them together under security at the operation level:

/secure-endpoint:
  get:
    security:
      - BearerAuth: []
        ApiKeyAuth: []

This requires both a Bearer token and an API key to be provided before the request can be sent. Try It! supports multiple security schemes in a single session, so developers can supply credentials for each and send one authorized request.

Sessions and security

• Credentials are session-only. The credentials a developer enters are kept only for the active session and are not saved. When the session ends, they must be entered again.
• Credentials are masked in the request preview. Sensitive values are hidden in the Request preview so they are not exposed on screen while building a request.

FAQ