Authentication

When your API needs a key or a token, declare how in the config. The reference then shows an Auth Required badge on secured operations, adds 401 and 403 responses, and gives readers an Authentication card. A key entered there fills every code sample and every test request.

Declare a security schemeCopy Anchor Link

Add the scheme under securitySchemes, then apply it with security:

apis: [
  {
    id: 'travel',
    source: { nest: { module: 'dist/app.module.js', build: 'nest build' } },
    securitySchemes: {
      apiKey: {
        type: 'apiKey',
        in: 'header',
        name: 'x-api-key',
        description: 'Your API key. Create one in the dashboard.',
      },
    },
    security: ['apiKey'],
  },
],

securitySchemes takes OpenAPI security scheme objects, keyed by a name you choose. security lists scheme names that every documented operation requires.

Common schemesCopy Anchor Link

securitySchemes: {
  apiKey: { type: 'apiKey', in: 'header', name: 'x-api-key' },
},

Secure only some routesCopy Anchor Link

Leave out security and mark routes with Swagger's decorators instead. The name must match a key in securitySchemes:

import { ApiBearerAuth } from '@nestjs/swagger';

@ApiBearerAuth('bearer') // matches securitySchemes.bearer
@Controller('bookings')
export class BookingsController {}

@ApiBearerAuth() without an argument uses the name bearer. @ApiSecurity('apiKey') works the same way for other schemes.

security in the config only applies to Nest sources, and it replaces each operation's own security. For a spec file, declare security in the spec itself.

ServersCopy Anchor Link

servers sets where requests go. It replaces the servers in the spec:

servers: [
  { url: 'http://localhost:3010', description: 'Local' },
  { url: 'https://api.orbit-travel.example', description: 'Production' },
],

With more than one server, the Server card in the introduction becomes a picker. The choice is remembered in the reader's browser.

• Code samples use the first server's URL.
• Test Request opens the API client with the environment of the selected server.
• A server whose URL or description contains prod or live becomes a production environment in the client. The client asks before sending to it.

The mock serverCopy Anchor Link

With mock in the config, a Mock server entry is added to the servers. That happens in orbitdocs dev, or always when you set mock.url for a hosted mock. Its credentials are pre-filled, because the mock accepts any key. See Mock server.

What readers seeCopy Anchor Link

The Authentication cardCopy Anchor Link

The introduction's right column shows an Authentication card for the API's schemes:

1. With several schemes, the reader picks one from the menu.
2. They type the value: the key, the token, or username:password for Basic.
3. The eye button shows or hides what they typed.

The value is stored in the reader's browser only, under orbitdocs:<api id> in localStorage. It is sent only to your API, with their requests.

Credentials in samplesCopy Anchor Link

Samples contain a placeholder until the reader enters a credential. Then the placeholder is replaced in every sample, and in what Copy copies.

An apiKey with in: 'cookie' is not added to samples.

Credentials in Test RequestCopy Anchor Link

Test Request opens the API client. The client's collection uses the operation's scheme with variables: {{apiKey}}, {{token}}, or {{username}} and {{password}}. The value from the Authentication card fills those variables when they are still empty.

Pre-filled for signed-in readersCopy Anchor Link

With private docs, your personalization hook can return each reader's own test key. The Authentication card is then filled in when they sign in. See Access rules.

Allow the docs origin in CORSCopy Anchor Link

Test Request sends real requests from the reader's browser. Unless the docs are served from the API's own origin, your API must allow the docs origin and the headers you use:

app.enableCors({
  origin: ['https://docs.orbit-travel.example', 'http://localhost:3000'],
  allowedHeaders: ['content-type', 'x-api-key', 'idempotency-key'],
});

Without it, the client shows Network error and suggests a CORS fix. Serving the docs from Nest avoids CORS entirely.

Next stepsCopy Anchor Link