Documentation

Providers & Auth

Model providers and the credentials behind them: list providers and their auth state, set or remove an API key, and run the OAuth authorize/callback pair.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected

Base URL Directory optional Bearer token optional

How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

8 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

get	/provider	provider.list
get	/provider/auth	provider.auth
post	/provider/{providerID}/api	provider.api.set
delete	/provider/{providerID}/auth	provider.auth.remove
post	/provider/{providerID}/oauth/authorize	provider.oauth.authorize
post	/provider/{providerID}/oauth/callback	provider.oauth.callback
put	/auth/{providerID}	auth.set
delete	/auth/{providerID}	auth.remove

get /provider # provider.list

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ProviderList application/json

{
  all: Provider[]
  default: {
    [key: string]: string
  }
  connected: string[]
}

Example response from schema

{
  "all": [
    {
      "id": "",
      "name": "",
      "source": "env",
      "env": [],
      "key": "",
      "options": {},
      "models": {}
    }
  ],
  "default": {},
  "connected": [
    ""
  ]
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

provider.list

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.provider.list({
  ...
})

Try it

directory query workspace query

get /provider/auth # provider.auth

Parameters

Name	In	Type	Required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ProviderAuthMethods application/json

{
  [key: string]: ProviderAuthMethod[]
}

Example response from schema

{}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

provider.auth

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.provider.auth({
  ...
})

Try it

directory query workspace query

post /provider/{providerID}/api # provider.api.set

Parameters

Name	In	Type	Required
providerID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  key: string
}

Responses

200 ProviderMutationSuccess application/json

{
  success: true
}

Example response from schema

{
  "success": true
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

provider.api.set

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.provider.api.set({
  ...
})

Try it

providerID path · required directory query workspace query

Request body application/json

delete /provider/{providerID}/auth # provider.auth.remove

Parameters

Name	In	Type	Required
providerID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 ProviderMutationSuccess application/json

{
  success: true
}

Example response from schema

{
  "success": true
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

provider.auth.remove

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.provider.auth.remove({
  ...
})

Try it

providerID path · required directory query workspace query

This changes or removes server state, against whatever base URL is set above.

post /provider/{providerID}/oauth/authorize # provider.oauth.authorize

Parameters

Name	In	Type	Required
providerID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  method: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}

Responses

200 Success application/json

  | {
  url: string
  method: "auto" | "code" | "auto-code"
  instructions: string
}
  | null

Example response from schema

{
  "url": "",
  "method": "auto",
  "instructions": ""
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

provider.oauth.authorize

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.provider.oauth.authorize({
  ...
})

Try it

providerID path · required directory query workspace query

Request body application/json

post /provider/{providerID}/oauth/callback # provider.oauth.callback

Parameters

Name	In	Type	Required
providerID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

{
  method: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  code?: string
}

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

provider.oauth.callback

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.provider.oauth.callback({
  ...
})

Try it

providerID path · required directory query workspace query

Request body application/json

put /auth/{providerID} # auth.set

Parameters

Name	In	Type	Required
providerID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Request body · required · application/json

OAuth | ApiAuth | WellKnownAuth

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

auth.set

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.auth.set({
  ...
})

Try it

providerID path · required directory query workspace query

Request body application/json

delete /auth/{providerID} # auth.remove

Parameters

Name	In	Type	Required
providerID	path	string	required
directory	query	string	optional
workspace	query	string	optional

Responses

200 Success application/json

boolean

Example response from schema

false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example

auth.remove

import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.auth.remove({
  ...
})

Try it

providerID path · required directory query workspace query

This changes or removes server state, against whatever base URL is set above.

Schemas

The 14 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

ApiAuth

{
  type: "api"
  key: string
}

Auth

OAuth | ApiAuth | WellKnownAuth

Model

{
  id: string
  providerID: string
  api: {
    id: string
    url?: string
    npm: string
  }
  name: string
  family?: string
  capabilities: {
    temperature: boolean
    reasoning: boolean
    attachment: boolean
    toolcall: boolean
    input: {
      text: boolean
      audio: boolean
      image: boolean
      video: boolean
      pdf: boolean
    }
    output: {
      text: boolean
      audio: boolean
      image: boolean
      video: boolean
      pdf: boolean
    }
    interleaved: 
      | boolean
      | {
      field: "reasoning_content" | "reasoning_details"
    }
  }
  cost: {
    input: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    output: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    cache: {
      read: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      write: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
    }
    experimentalOver200K?: {
      input: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      output: 
        | number
        | "Infinity" | "-Infinity" | "NaN"
      cache: {
        read: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
        write: 
          | number
          | "Infinity" | "-Infinity" | "NaN"
      }
    }
  }
  limit: {
    context: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    input?: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
    output: 
      | number
      | "Infinity" | "-Infinity" | "NaN"
  }
  status: 
    | "alpha"
    | "beta"
    | "deprecated"
    | "active"
  options: { [key: string]: unknown }
  headers: {
    [key: string]: string
  }
  release_date: string
  variants?: {
    [key: string]: { [key: string]: unknown }
  }
}

OAuth

{
  type: "oauth"
  refresh: string
  access: string
  expires: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  accountId?: string | null
  enterpriseUrl?: string | null
}

Provider

{
  id: string
  name: string
  source: 
    | "env"
    | "config"
    | "custom"
    | "api"
  env: string[]
  key?: string | null
  options: { [key: string]: unknown }
  models: {
    [key: string]: Model
  }
}

ProviderApiPayload

{
  key: string
}

ProviderAuthMethod

{
  type: "oauth" | "api"
  label: string
}

ProviderAuthMethods

{
  [key: string]: ProviderAuthMethod[]
}

ProviderList

{
  all: Provider[]
  default: {
    [key: string]: string
  }
  connected: string[]
}

ProviderMutationSuccess

{
  success: true
}

ProviderOAuthAuthorization

{
  url: string
  method: "auto" | "code" | "auto-code"
  instructions: string
}

ProviderOAuthAuthorizeInput

{
  method: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}

ProviderOAuthCallbackInput

{
  method: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  code?: string
}

WellKnownAuth

{
  type: "wellknown"
  key: string
  token: string
}