Testing endpoints with Try it!

Try It! is Document360's interactive API console, embedded directly in your published API reference. It lets developers send real requests to your API endpoints and see live responses without leaving the documentation or writing any code.

This article explains how Try It! works, what developers need to use it, and how to configure each supported authentication method in your API specification.

What Try It! does

From any endpoint page in your published API reference, developers can:

• Select an HTTP method and endpoint
• Fill in required and optional parameters
• Configure authentication credentials
• Send a live request and view the response in real time
  

Requirements for Try It! to appear

Try It! only appears on an endpoint page when both of the following are correctly defined in your API specification file:

• A server URL - the servers section of your spec must contain at least one valid base URL.
• A server variable - the variable must be defined alongside the URL.

If either of these is missing, the Try It! button will not be visible on the Knowledge base site.

Correct server URL format

servers:
  - url: https://api.yourdomain.com
    description: Production

For APIs with multiple regions, define multiple entries:

servers:
  - url: https://api.yourdomain.com
    description: Global

  - url: https://api.us.yourdomain.com
    description: US region

How requests are routed

When a developer clicks Try it & see response, the request URL will include tryit.document360.io prepended to your API's base URL. For example:

https://tryit.document360.io/https://api.yourdomain.com/v2/your-endpoint

This is expected behavior. The tryit.document360.io subdomain is used internally to route and process API test requests. It does not affect functionality, but requests still return the correct results from your API.

Supported authentication methods

Document360 reads the authentication configuration directly from your OpenAPI specification and surfaces it in two places: the endpoint documentation and the Try It! console.

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

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 Try It!, developers will be prompted to enter a username and password before sending a request.

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: []

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 Try It!, developers will be prompted to enter their API key value. It will be sent in the header name defined in your spec (X-API-Key in the example above).

OAuth2

OAuth2 is supported with four flows. Use the flow that matches how your API issues access tokens.

Required configuration for Try It!

When your API uses OAuth2, two additional settings must be configured:

Redirect URI — After a developer completes the OAuth authorization flow, they are redirected back to Document360. Add Document360's redirect URI to your OAuth provider's list of allowed redirect URIs:

https://your-apidocs-domain.com/oauth

Replace your-apidocs-domain.com with the domain your Document360 API documentation is published on.

Silent renewal — Document360 automatically refreshes the OAuth access token in the background while a developer is actively using Try It!. This prevents the session from expiring mid-use. No configuration is required on your end because this is handled automatically by Document360.

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

OpenID Connect

OpenID Connect extends OAuth2 by adding user identity verification. It is configured similarly to OAuth2 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

The same redirect URI requirement applies:

https://your-apidocs-domain.com/oauth

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.

What Try It! does not support

• Webhooks - Try It! is not available for webhook definitions. Webhook pages show the payload schema and an example but cannot send test requests.
• Instance-based dynamic responses - Document360 follows the OpenAPI specification, which defines a consistent static structure for request and response objects. If your API returns different responses for the same endpoint across different environments or instances, Try It! will reflect only what is defined in the spec.

FAQ