Make your first call

What this does for you

You go from no credential to one authenticated request and the answer it returns.

Before you start

• A Botseon account. On your own you are your personal organisation's owner, so you create every kind of key. In a team, any member who is not a guest creates Read and Read and write keys that act as them, with nobody to ask — unless an administrator has limited key creation to administrators. An Admin key and an organisation key are an administrator's, and a guest creates none (Authentication and keys).
• The API keys page in the app: Settings → API keys (/settings/api-keys). On a team it is also in the organisation nav, as API keys. It is where a key is created.
• The address your install answers on. The samples below read it from BOTSEON_API_URL — the same variable the SDKs read — and the key from BOTSEON_API_KEY; a page never prints the value of either.
• A terminal, or Node with @botseon/sdk installed (The TypeScript SDK and headless mode).

Steps

These steps are followed at a terminal and on the API keys page; the API itself has no screen of its own, so no screenshot is shown here.

1. Open Settings → API keys. If the page says only administrators can create keys, ask an administrator to make one for you or to lift that restriction.
2. Give the key a Name of 1 to 60 characters, choose a Scope, and choose when it Expires. The scope is Read, Read and write or Admin (offered to administrators only), and Read is the default; the expiry is 7, 30, 90, 180 or 365 days, and 90 days is the default. An administrator on a team also chooses the Owner: Me, or Organisation for a key that keeps working when its maker leaves.
3. Press Create key. The full key is shown once, under Copy your key now. Copy it, then press Done.
4. Put the key in your shell's environment under BOTSEON_API_KEY, and your install's address under BOTSEON_API_URL. Do not pass a key on a command line: a command line is visible to every process and every log.
5. Send one read request. The answer is a JSON body with data and nextCursor, and the response carries an x-request-id header you can quote in a support request.
6. When you are finished with the key, press Revoke on its row in the Keys list on the same page. A revoked key is refused on the next request.

A worked example

List the bots your key's person can see:

curl -sS "$BOTSEON_API_URL/api/v1/bots?limit=5" \
  -H "authorization: Bearer $BOTSEON_API_KEY" \
  -H "accept: application/json"

The same call from Node, reading the two variables from the environment:

const res = await fetch(`${process.env.BOTSEON_API_URL}/api/v1/bots?limit=5`, {
  headers: {
    authorization: `Bearer ${process.env.BOTSEON_API_KEY}`,
    accept: 'application/json',
  },
});
if (!res.ok) throw new Error(`bots: ${res.status}`);
const page = (await res.json()) as { data: Array<{ id: string; name: string }>; nextCursor: string | null };
for (const bot of page.data) console.log(bot.id, bot.name);

What can go wrong

The first cell is the code the error envelope carries; the sentence beside it in error.message is fixed and nothing interpolates into it.

See also

• Authentication and keys
• Envelopes, errors, idempotency and paging
• Runs
• The TypeScript SDK and headless mode