Authentication examples

The playground supports four common auth schemes. Pick whichever your API uses, configure once in Project Settings → API → Authentication, and every endpoint inherits the setup.

Bearer token#

The most common pattern for modern APIs. The reader pastes a token; Dokly sends it as Authorization: Bearer <token>.

Configure#

Type:    Bearer
Header:  Authorization
Prefix:  Bearer

What the reader sees#

A "Bearer token" input field above the request form. The token is stored in browser localStorage; it's never sent to Dokly servers.

In your OpenAPI spec#

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
security:
  - BearerAuth: []

If your spec defines BearerAuth like this, the playground picks it up automatically — no manual config needed.

API key#

For APIs that use a long-lived key passed in a header or query param.

Configure#

Type:        API key
Location:    Header   (or Query)
Name:        X-API-Key   (or whatever your API uses)

What the reader sees#

An "API key" input field. The key is added to the configured header or query parameter on every request.

In your OpenAPI spec#

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

Basic auth#

Username + password, sent as a base64-encoded Authorization: Basic header. Rare in modern APIs; common in admin panels and legacy systems.

Configure#

Type:   Basic
Realm:  (optional, shown as a hint to the reader)

What the reader sees#

Two input fields — username and password. Dokly base64-encodes them before sending.

OAuth 2.0#

For APIs that require a full OAuth flow.

Configure#

Type:           OAuth 2.0
Flow:           Authorization Code   (or Client Credentials)
Authorize URL:  https://your-api.com/oauth/authorize
Token URL:      https://your-api.com/oauth/token
Scopes:         read:users, write:users   (one per line)
Client ID:      (your OAuth app's client ID)

What the reader sees#

A "Sign in with..." button that opens the OAuth flow in a new window. After consent, the access token is captured automatically and used for subsequent requests.

Setting up the OAuth app#

You'll need to register an OAuth app with your provider and add Dokly's redirect URI to the app's allowed callbacks:

https://docs.your-domain.com/api/auth/oauth-callback

Or for projects on a Dokly subdomain:

https://your-subdomain.dokly.co/api/auth/oauth-callback

Multiple auth schemes#

Some APIs support multiple auth methods (e.g., Bearer for users, API key for service accounts). Configure all of them — readers see a tabbed picker above the request form.

You can also override per-endpoint by setting the auth prop on the playground component:

<APIPlayground
  method="GET"
  url="https://api.example.com/v1/public/status"
  auth="none"
/>

Mock authentication for testing#

For the most common case — letting readers try the playground without signing up for your API first — provide a sandbox.

A common pattern:

1. Run a sandbox version of your API at sandbox.your-api.com.
2. Make the sandbox accept a hardcoded test token (e.g., Bearer test_token).
3. Document the test token prominently in your "Authentication" doc.
4. Configure the playground to default to the sandbox URL.

Readers go from "find docs" to "first 200 response" in under a minute. That's the activation moment that turns prospects into users.

Where next#