> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks credential setup

> Store the Kyberis API key in a Databricks secret scope, wire app secret resources, and rotate keys.

Everything here follows one rule: **the Kyberis API key exists only in Databricks
secret storage.** It is never placed in notebooks, widgets, job parameters,
cluster environment variables, workspace files, or repository files — all of
those are readable by other users, or end up in logs and exports.

## Get an API key

Create an API key in the Kyberis dashboard under **Settings → API keys**. You get
a key ID and a secret. The integration needs the standard customer read scopes —
resolution, evidence, relationships, intel, assessments, and batch — which the
default key scopes cover.

## Store it in a secret scope

```bash theme={null}
databricks secrets create-scope kyberis
databricks secrets put-secret kyberis kyberis-api-key-id      # paste the key id
databricks secrets put-secret kyberis kyberis-api-key-secret  # paste the secret
```

Grant analysts and jobs that run the notebooks **READ** on the scope:

```bash theme={null}
databricks secrets put-acl kyberis <user-or-group> READ
```

Notebooks read it with `dbutils.secrets.get`, which Databricks **redacts in cell
output**, so the value cannot be casually printed. The helper package immediately
exchanges it for a short-lived bearer token, with roughly a 30-minute TTL, so
requests carry the long-lived secret only on the mint call
(`POST /v2/auth/token`) and not on every enrichment call.

## Databricks App

The app never touches secret scopes directly. When creating or editing the app,
add two **Secret resources**:

| Resource key, used in the `app.yaml` `valueFrom` | Points at |
| - | - |
| `kyberis-api-key-id` | Scope `kyberis`, key `kyberis-api-key-id` |
| `kyberis-api-key-secret` | Scope `kyberis`, key `kyberis-api-key-secret` |

Databricks injects them as the environment variables `KYBERIS_API_KEY_ID` and
`KYBERIS_API_KEY_SECRET` into the app process only, and grants the app's service
principal READ on the scope. The app renders neither value, and its
`KyberisCredentials` type redacts the secret from `repr()` and exceptions.

## Rotation

1. Create a new API key in the Kyberis dashboard.
2. Run `databricks secrets put-secret` for both keys with the new values.
3. Restart the app (**Compute → Apps → Stop**, then **Start**) so it re-reads the
   environment. Notebooks and jobs pick the new values up on their next run.
4. Revoke the old key in Kyberis.

<Note>
  Revoking a Kyberis API key blocks *future* bearer-token mints. A token minted
  just before revocation stays valid until it expires, within 30 minutes.
</Note>

## Base URL

`KYBERIS_API_BASE_URL` is optional — set it as an environment variable, or leave
the code default `https://api.kyberis.ai`.

Only `https` is accepted, and this is enforced rather than advised: a plaintext
override raises at startup instead of being honoured, because this URL is where
the API key travels on token mint and where every bearer token goes after that.
`http://localhost` and `http://127.0.0.1` are exempt, so you can point the app at
a local mock during development.