Authentication

Every SDK resource request carries a Coresource API key. The SDK reads it from the environment by default, and every entry point accepts it explicitly when you would rather it came from somewhere else.

Your API key#

Create one in the console, then put it in the environment:

export CORESOURCE_API_KEY='your-api-key'

That is all createAgent() and new CoreSource() need. Neither takes any required options.

import { createAgent, CoreSource } from '@coresourceai/sdk';

// Both read CORESOURCE_API_KEY.
const agent = createAgent({ type: 'one-shot' });
const coresource = new CoreSource();

await agent.close();

If the key is missing, the first call that needs it throws a TypeError:

Passing the key explicitly#

In a server that loads secrets from a vault, or anywhere you would rather not put a credential in the environment, pass it directly. The second argument to createAgent() and the only argument to new CoreSource() are the same shape.

import { createAgent } from '@coresourceai/sdk';

const agent = createAgent(
  { type: 'agent', systemPrompt: 'Be careful.' },
  { apiKey: await loadKeyFromYourSecretStore() }
);

await agent.close();

declare function loadKeyFromYourSecretStore(): Promise<string>;

An explicit apiKey always wins over the environment, so one process can talk to more than one account.

Connection options#

ttlSeconds is forwarded only when local tools, local skills, runtime tools, or local MCP cause the SDK to provision a bridge. The bridge accepts an integer from 60 seconds through 30 days.

Pointing at another deployment#

export CORESOURCE_API_URL='https://api.example.com/v1/'

Or per-instance, which is the better choice when one process talks to several environments:

import { CoreSource, createAgent } from '@coresourceai/sdk';

const staging = createAgent(
  { type: 'agent' },
  { baseUrl: 'https://api.staging.example.com/v1/' }
);

const production = new CoreSource({
  baseUrl: 'https://api.coresource.ai/v1/'
});

await staging.close();

Supplying your own fetch#

fetch is the supported seam for request logging, a corporate proxy, or your own retry layer. It receives and returns the standard fetch signature, so wrapping the global one is usually enough.

import { createAgent } from '@coresourceai/sdk';

const agent = createAgent(
  { type: 'agent' },
  {
    fetch: async (input, init) => {
      const startedAt = Date.now();
      const response = await fetch(input, init);
      console.log(response.status, Date.now() - startedAt, String(input));
      return response;
    }
  }
);

await agent.close();

Keeping keys safe#

Never ship a key to a browser. The SDK is a server-side library; a key in client JavaScript is a key you have published. Put a route in your own backend between the browser and Coresource.

Scope keys per environment. Separate keys for staging and production mean you can rotate one without an outage in the other.

Do not log error objects raw. The SDK redacts known credential patterns in error messages and serialized error details, but application logs should still treat request and error data as sensitive. See errors and retries.