# Credentials (https://docs.neuralisapp.com/agent-core/credentials)

Every secret agent-core uses lives in the encrypted credential store, never in
platform settings or an environment variable. A lookup carries the caller's
scope and resolves **most-specific-wins** — agent → project → user → global —
so two projects can use different keys, and one agent can be pinned to its
own. The store, its scopes and the owner/admin surface are described on
[package-system credentials](https://docs.neuralisapp.com/package-system/credentials.md).

## What agent-core declares [#what-agent-core-declares]

Declaring an id only lists it in the admin catalog for an owner to set; it
grants nobody the right to write it.

| Group | Ids | Used for |
| --- | --- | --- |
| Model providers | `llm.anthropic`, `llm.openai`, `llm.gemini`, `llm.xai`, `llm.deepseek`, `llm.kimi`, `llm.qwen`, `llm.minimax`, `llm.openai-codex.oauth` | The provider keys (the Codex entry is the ChatGPT-subscription sign-in) — see [providers and models](https://docs.neuralisapp.com/agent-core/providers-and-models.md). Custom endpoints add `llm.endpoint.<id>`. |
| Web search | `websearch.tavily`, `websearch.brave` | The keyed search providers; without a key a provider is skipped, never failed. |
| Git OAuth apps | `github.oauth.clientId` / `…clientSecret`, and the same pair for `gitlab`, `bitbucket`, `codeberg` | The one-click git connect (below). The GitHub pair also drives the GitHub MCP connect. |
| Channel OAuth app | `oauth.whatsapp.clientId` / `…clientSecret` | *Sign in with WhatsApp* — see [channels](https://docs.neuralisapp.com/agent-core/channels.md). |

## Your own keys [#your-own-keys]

Some work needs a key only *you* have — a personal OpenAI key, a token for a
service only you are licensed for, a secret a skill you use expects. The chat
config panel's **Credentials** card stores it in your own scope, with no
administrator involved. It needs `credentials.self`, which managers and members
hold by default; without it the card is not shown.

**What the list shows.** Every credential id declared by a package or skill
that is already visible to you in this project, with its category and who
requires it, plus any custom id you added yourself. A package you are
feature-hidden or scope-hidden from never reveals its ids here, and if the
platform cannot confirm what you may see, it shows nothing. Each row's
**set / not set** badge reflects **only your own user scope** — never whether an
owner set a project or platform value behind it.

**Setting a value.** **Set** (or **Replace**) on a row, or **+** for an id of
your own (letters, digits, `_`, `.`, `-` — for example `OPENAI_API_KEY`).
Values are **write-only**: once saved, the card and the whole API only ever
report whether a value is present. Everything lands in **your own user scope**
and nowhere else — there is no scope picker, and the route hard-codes your
identity, so the surface cannot write to another user, a project or an agent.

**How your key gets used.** It is your value for any package or skill that
resolves that id while running as you:

- with no agent- or project-scope value, your key is used;
- an owner's **project or agent key always wins** over yours inside that
  project — your key is a personal fallback, never an override;
- a **skill script** is the exception, because its value lands in a shell you
  control: a skill you run reads only your own key unless your role holds
  `project.credentials.write` (agent and project keys) and `platform.scope`
  (global keys). An administrator's key is never projected into your shell.

One family never reads your scope: the embedding keys (`embedding.*`). Indexing
runs as background platform work with one shared vector collection, so those
ids resolve at the global scope only — a value you store there is kept but
never used.

**What you cannot set here.** Git remote tokens (`git.<host>.…`), channel
secrets (`telegram.…`, `whatsapp.…`) and outbound MCP secrets (`mcp.<server>.…`)
are excluded and refused by hand, because each has its own connect surface that
validates it — the Git remotes group, the Channels panel, and the MCP server's
own row.

**Connected accounts.** The same card lists every account you signed in to or
seeded a token for — each MCP server sign-in, each git host, and your
ChatGPT / Codex sign-in — read from your own user scope across every project:
the account, which stored ids it holds, and its expiry when the provider stated
one, never a value. **Revoke** on a row removes it through that account's own
connect surface: an MCP sign-in loses its access and refresh token (a static
client id/secret you seeded stays for the next sign-in), a git host loses its
PAT and OAuth tokens together, and ChatGPT / Codex is disconnected and revoked
at OpenAI. An administrator holding `platform.scope` sees the same ids under the
admin Credentials surface's **User** scope for any member of their own projects.

**If the card disappears.** An owner can switch member self-service off by
removing `credentials.self` from the project's roles. New writes are then
refused, but a value you stored while it was granted keeps working, because
your user scope is global to you; an owner removes it from the admin
Credentials surface if it must go.

Every set and delete is recorded in the audit log by id, never with the value.
An agent reads which ids you have filled with the read-only `my-credentials`
skill; it can never set one, because a value passed as a tool argument would
persist in the conversation.

## Git remotes [#git-remotes]

A **git remote** connection gives you and your agents the credentials to
`push`, `pull` and `fetch` against a hosted provider. It is **personal and
HTTPS-only**: `git.connect` is a member default, each user connects their own
remote, and the push token lands encrypted in that user's scope — there is no
SSH key path, and the token is never echoed back. Connecting only stores the
credential and a small non-secret binding (host, account, auth kind); running
git is separate and needs the usual filesystem rights.

Open the **Connections** section of the chat config panel and find the **Git
remotes** group (visible with `git.connect`; the server re-checks the feature
on every request). Two ways land the same token:

- **Paste a Personal Access Token** — works with any host. Use this for
  self-hosted Gitea or Forgejo, generic remotes and Azure DevOps, which the
  OAuth flow refuses by name.
- **One-click OAuth** — for **github.com**, **gitlab.com**, **bitbucket.org**
  and **codeberg.org** only. The token exchange sends your OAuth App's client
  secret to the host, so Neuralis sends it only to an endpoint it knows in
  advance, never to an address someone typed in. The panel's button starts the
  GitHub flow; the other three hosts are reachable through the API.

The exchange runs server-side over a guarded, address-pinned HTTPS request, and
the token never reaches the page. Pending flows are single-use and short-lived,
and a callback that does not match the user who started the flow is refused.
Disconnecting removes every stored token for that host — and its OAuth pair —
in one idempotent step.

What a grant may do differs per host: **GitHub** asks for `repo`; **GitLab**
for `read_repository write_repository`; **Bitbucket** sends no scope (the
consumer's registered permissions apply, so grant it repository read + write
when you register it); **Codeberg** sends no scope because Forgejo implements
none, so its token carries your **full account rights** — use a scoped personal
access token there if that matters.

### Registering the OAuth App [#registering-the-oauth-app]

The one-click flow needs an OAuth App on each host, registered once, with the
callback URL set to your public Neuralis origin:

```
https://<your-neuralis-origin>/api/oauth/callback
```

The host issues a Client ID and Client Secret; store them as the host's
`<host>.oauth.clientId` / `<host>.oauth.clientSecret` pair. The pair is chosen
from the host you are connecting, never from the request. Two ways to run it:

- **Owner-provisioned (recommended)** — an owner stores one organization App at
  the platform or project scope on the admin Credentials surface, and every
  member's connect uses it.
- **Member self-seeded** — a member stores their own pair in their user scope
  from [Your own keys](#your-own-keys); it overrides the shared App for their
  own flows.

The pair is resolved at the same scope at the start and the end of the flow. If
no Client ID resolves, the flow fails cleanly and the PAT path stays available.
Keep the two kinds apart: the App pair is the *application's* identity; the
push token is the *user's* credential and always stays in that user's scope.
Shared project- or agent-scope git tokens are managed on the admin Credentials
surface.

Running git happens in the Files widget's **Git Control** panel, or for an
agent through brain-core's `git` skill on the same routes. Both need your
filesystem **write** feature and the source's **`exec`** policy, and each
operation releases your token only to the exact connected host over HTTPS. See
[brain-core app surfaces](https://docs.neuralisapp.com/brain-core/app-surfaces.md).

## Connector and MCP secrets [#connector-and-mcp-secrets]

A package connector has no credential store of its own: it declares the ids it
needs in its manifest and reads them through the resolver the platform injects
into its package — the same encrypted, audited store. The connector lifecycle
itself sends no auth headers, so a connector that needs authentication resolves
its credential in its own package code. The child environment is sanitized
before any spawn, and secrets never appear in tool inputs or model context.

An external MCP server's OAuth tokens, header secrets and sidecar environment
values are stored in your own user scope from that server's row — see
[MCP servers](https://docs.neuralisapp.com/agent-core/routes.md#mcp-servers).
