Security

Every request to Grepvine, from an SDK, gv, an MCP client or the console, goes through one API. The API decides who is calling and what that caller may do before the request reaches any index.

Authentication.

Grepvine has two kinds of credential:

• API keys are for programs: the SDKs, gv, the MCP server and direct API calls. A key is sent as Authorization: Bearer gvk_…. It has no expiry, and works until it’s revoked or its user is disabled.
• Console sessions are for people, and last 24 hours. Changing your password ends all your other sessions, but doesn’t revoke any API key.

gv login gets a key through the console. It prints a code and opens a browser, where you approve the code while signed in. The code expires after 10 minutes. Approve only a code you just requested, and check that the browser shows the same code as your terminal.

Access controls.

Roles.

Access is granted per organization. A user’s role in an organization, owner, admin, developer or reader, sets what the user and every key of theirs can do there. Concepts lists what each role allows. Owners and admins manage members:

gv member add acme support-agent --role reader
gv member set-role acme dana developer
gv member rm acme lee

Give each user the lowest role that covers its work:

Who	Role
An agent that searches and reads	reader
A job that uploads or syncs documents	developer
A person who creates indexes and manages members	admin

A developer can write to an index but can’t create one. Create indexes yourself, and the job that fills them needs only developer.

A role change or a removal reaches every API server within 10 seconds. Removing a member is also how you cut off their keys: a key belongs to its user, and only that user can revoke it.

API keys carry their user’s roles.

A key has no scope of its own. It can do whatever its user can, in every organization the user belongs to. To give an agent less access than you have:

1. Create a separate Grepvine user for the agent.
2. Add that user only to the organizations the agent needs, with the reader role.
3. Sign in as that user and create the agent’s key.

Tool permissions in an MCP client, such as the Claude Code rules that deny put_documents, stop an agent from calling a tool. The key itself can still write if its user’s role allows it. When an agent must not write, give it a reader’s key.

Support access.

When Grepvine support needs to read your documents or run a query, for example to reproduce a problem you reported, it gets a membership in your organization like any other member’s. That membership has the developer or reader role, lasts at most 72 hours and then ends on its own. The console’s member list shows it with “access until” and the end time, and gv member ls --json shows it with expires_at.

Manage API keys.

Create a key in the console under API keys, or with gv:

gv key create github-actions > github-actions.key

The key is shown once. Grepvine doesn’t keep it in a form it can show again. It shows the first 12 characters, the prefix, so you can tell keys apart. gv key ls lists your keys with their prefixes and when each one last authenticated a request:

$ gv key ls
ID                                    NAME            PREFIX        CREATED               LAST USED             REVOKED
0192f4a1-3c2e-7b10-8d4f-5a6b7c8d9e01  gv              gvk_7Hq2mXc9  2026-09-14T08:12:44Z  2026-11-03T09:41:07Z  -
0192f4b8-91d0-7e22-a3c5-0f1e2d3c4b5a  github-actions  gvk_Lp4wZt8R  2026-09-20T15:03:10Z  2026-11-03T07:58:31Z  -
0192f4c2-07ab-7f45-b6e8-9a8b7c6d5e4f  support-agent   gvk_c3Vn0yQe  2026-10-01T10:00:00Z  2026-10-02T17:22:19Z  -

gv key rm ID revokes a key. The API server that handles the revocation refuses the key at once, and every other API server within 10 seconds. You can list and revoke only your own keys.

Best practices for API keys.

• Create one key for each place it runs. Give each machine, CI job and agent its own key, named after it. You can then revoke one without breaking the others, and LAST USED shows which are still in use.
• Keep keys out of code and prompts. Pass a key in GREPVINE_API_KEY from your secret store, and refer to the variable in configuration files, as ${GREPVINE_API_KEY} does in .mcp.json. Don’t paste a key into an agent’s chat or system prompt, where it stays in the conversation and in any log of it.
• Use https:// endpoints only. The API redirects http:// to https://, but by then the key has crossed the network in clear text. If you override the endpoint in an SDK or gv, keep the https:// scheme.
• Protect gv’s configuration file. gv login saves the key in ~/.grepvine/config.yaml with mode 0600, and gv refuses to read the file if other users can. Don’t commit it or copy it into a container image. gv logout deletes the key from the file but doesn’t revoke it.
• Scan for leaked keys. A key is gvk_ followed by 43 characters of base64url. Add gvk_[A-Za-z0-9_-]{43} to your secret scanner and pre-commit hooks.
• Revoke keys nobody uses. Keys never expire. Revoke a key as soon as the machine, job or agent it was created for is gone, and revoke any key whose LAST USED is - or months old.

Rotate a key.

1. Create the new key and deploy it, for example as the CI job’s secret:

   gv key create github-actions-2026-11 > github-actions.key

2. Run gv key ls until the old key’s LAST USED stops changing, which means nothing uses it any more.

3. Revoke the old key with gv key rm ID.

If a key leaks.

1. Revoke it at once with gv key rm ID or in the console, before its replacement is ready. Every API server refuses it within 10 seconds.
2. Create a replacement and deploy it.
3. If your password may be exposed too, change it. That ends your other console sessions, but your other keys stay valid until you revoke them.

If the leaked key belongs to someone else, ask them to revoke it. Until they do, an owner or admin can remove that user from the organization.

Data in transit and at rest.

• In transit. The API and the MCP server accept HTTPS only, with TLS 1.2 or 1.3.
• At rest. Object storage encrypts every index with keys held in AWS Key Management Service. The servers’ disks, including the NVMe cache, are encrypted as well.

Report a vulnerability.

Report a vulnerability privately, not in a public issue. Email security@treeverse.io, or use Report a vulnerability on the Security tab of the affected repository on GitHub, such as grepvine-cli. Include the steps to reproduce the problem and the impact you expect.