Authentication
Your SDK's authentication comes from the security schemes in your spec. By default, it follows them exactly, so the client, your docs and the playground all agree without you doing anything.
Choosing a scheme
Authentication schemechoice or listSet it in SDK Studio.
| Value | Studio label | What the client does |
|---|---|---|
inherit | Project default | Follows your project's API settings, then your spec's security schemes |
none | None | Sends no credentials. For public APIs |
bearer | Bearer token | Accepts a token, sent as Authorization: Bearer <token> |
apiKey | API key | Accepts an API key |
basic | Basic | Accepts a username and password |
oauth2 | OAuth 2.0 | Accepts an OAuth 2 token, or runs the flow itself |
You can select several of bearer, apiKey, basic and oauth2 together. inherit and none stand alone. The client then accepts a credential for each, and sends each one only on the operations whose security requirement accepts that scheme.
auth, such as bearer or ["apiKey", "bearer"]
Base URLURLThe address the client calls unless the caller passes another.
baseUrl
Selecting apiKey or basic doesn't describe the credential on its own, because the client needs to know where to send it. If your spec doesn't declare that kind of scheme, the build's client has no field for it, and its README says "This build does not declare an authentication scheme". Declare it under components.securitySchemes.
bearer is the exception, because its format is fixed: it works whether or not your spec declares it.
Declaring it in your spec
Each scheme becomes a field on the client, named after the scheme:
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- apiKeyAuth: []Pick a readable scheme name, since developers will type it: apiKeyAuth here gives them auth: { apiKeyAuth: "..." }.
An operation's own security overrides the document's. Use security: [] on a public endpoint so no credential is sent there.
What developers write
These are from generated TypeScript clients. The generated README lists the fields and headers for that build.
const client = new Acme({
auth: { bearer: process.env.API_TOKEN! },
});Sent as Authorization: Bearer <token>.
OAuth 2
An OAuth 2 scheme accepts any of three forms. In these examples, the scheme is named oauth.
const client = new Acme({
auth: { oauth: { accessToken: process.env.API_TOKEN! } },
});Choosing what to offer
Your spec says what your API accepts, but the SDK setting is separate on purpose. An API often accepts several schemes while the SDK should encourage one. If your API takes both a long-lived key and a short-lived OAuth token, you can steer developers toward the safer one by offering only that, without blocking the other.
Keeping credentials out of the package
The client only uses the credentials a developer passes it. Nothing is built into the package, so an SDK on a public registry carries no secret.
A hook is compiled into the published package. A credential hard-coded in one goes to npm or PyPI with it. Read credentials from the caller's config or their environment.
Troubleshooting
The MCP server
The MCP server's operation tools call your real API, and take credentials through their own environment variables. See MCP configuration.
From the CLI
octri sdk settings set auth bearer changes the scheme. The keys are in the settings reference, and the command in SDK commands.