BYOK - OpenRouter | Documentation

Overview

BYOK endpoints

Available Operations

list - List BYOK provider credentials
create - Create a BYOK provider credential
delete - Delete a BYOK provider credential
get - Get a BYOK provider credential
update - Update a BYOK provider credential

list

List the bring-your-own-key (BYOK) provider credentials for the authenticated entity’s default workspace, or a workspace-scoped management key’s own workspace. Use the workspace_id query parameter to scope the result to a different workspace, or the provider query parameter to filter by upstream provider. A workspace-scoped management key can only list its own workspace; any other workspace_id returns 403. Management key required.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.byok.list();

  for await (const page of result) {
    console.log(page);
  }
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { byokList } from "@openrouter/sdk/funcs/byokList.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await byokList(openRouter);
  if (res.ok) {
    const { value: result } = res;
    for await (const page of result) {
    console.log(page);
  }
  } else {
    console.log("byokList failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.ListBYOKKeysRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.ListBYOKKeysResponse>

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

create

Create a new bring-your-own-key (BYOK) provider credential. The raw key is encrypted at rest and never returned in API responses. When workspace_id is omitted, the credential is created in the default workspace; if that default has been deleted, the request returns a 400 and you must pass workspace_id explicitly. A workspace-scoped management key creates the credential in its own workspace when workspace_id is omitted, and any other workspace_id returns 403. Treat the raw key as write-only; it is never returned after creation. Use allowed_api_key_hashes to restrict the credential to specific OpenRouter API keys. Management key required.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.byok.create({
    createBYOKKeyRequest: {
      key: "sk-proj-abc123...",
      name: "Production OpenAI Key",
      provider: "openai",
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { byokCreate } from "@openrouter/sdk/funcs/byokCreate.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await byokCreate(openRouter, {
    createBYOKKeyRequest: {
      key: "sk-proj-abc123...",
      name: "Production OpenAI Key",
      provider: "openai",
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("byokCreate failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.CreateBYOKKeyRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.CreateBYOKKeyResponse>

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

delete

Delete (soft-delete) a bring-your-own-key (BYOK) provider credential by its id. The encrypted key material is wiped and the record is marked as deleted. A workspace-scoped management key only reaches credentials in its own workspace; any other id returns 404. Management key required.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.byok.delete({
    id: "11111111-2222-3333-4444-555555555555",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { byokDelete } from "@openrouter/sdk/funcs/byokDelete.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await byokDelete(openRouter, {
    id: "11111111-2222-3333-4444-555555555555",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("byokDelete failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.DeleteBYOKKeyRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.DeleteBYOKKeyResponse>

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get

Get a single bring-your-own-key (BYOK) provider credential by its id. A workspace-scoped management key only reaches credentials in its own workspace; any other id returns 404. Management key required.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.byok.get({
    id: "11111111-2222-3333-4444-555555555555",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { byokGet } from "@openrouter/sdk/funcs/byokGet.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await byokGet(openRouter, {
    id: "11111111-2222-3333-4444-555555555555",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("byokGet failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.GetBYOKKeyRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.GetBYOKKeyResponse>

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

update

Update an existing bring-your-own-key (BYOK) provider credential by its id. Include the key field to rotate the raw provider API key in-place (the previous key material is overwritten). Use allowed_api_key_hashes to restrict the credential to specific OpenRouter API keys (null clears the restriction). A workspace-scoped management key only reaches credentials in its own workspace; any other id returns 404. Management key required.

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.byok.update({
    id: "11111111-2222-3333-4444-555555555555",
    updateBYOKKeyRequest: {
      disabled: false,
      name: "Updated OpenAI Key",
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { byokUpdate } from "@openrouter/sdk/funcs/byokUpdate.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await byokUpdate(openRouter, {
    id: "11111111-2222-3333-4444-555555555555",
    updateBYOKKeyRequest: {
      disabled: false,
      name: "Updated OpenAI Key",
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("byokUpdate failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.UpdateBYOKKeyRequest	✔️	The request object to use for the request.
`options`	RequestOptions	➖	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.UpdateBYOKKeyResponse>

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.ConflictResponseError	409	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

​Overview

​Available Operations

​list

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​create

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​delete

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​get

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​update

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

Overview

Available Operations

list

Example Usage

Standalone function

Parameters

Response

Errors

create

Example Usage

Standalone function

Parameters

Response

Errors

delete

Example Usage

Standalone function

Parameters

Response

Errors

get

Example Usage

Standalone function

Parameters

Response

Errors

update

Example Usage

Standalone function

Parameters

Response

Errors