> ## Documentation Index
> Fetch the complete documentation index at: https://helix-isolate-failing-index-entities.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# helix service-credential

> Manage workspace-owned credentials for headless HTTP API and unified MCP clients

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

Create and manage service credentials: workspace-owned secrets that let headless automation call
Helix Cloud. You manage them with your WorkOS login, but they never log the CLI in. Cloud only.

Owners and admins need the workspace-scoped `service_credentials.manage` permission.

## Usage

```bash theme={null}
helix service-credential create --name <name> \
  --grant <project-id>=project-read,query-read [--expires-at <RFC3339>]
helix service-credential [list]
helix service-credential get <CREDENTIAL>
helix service-credential update <CREDENTIAL> \
  [--name <name>] [--grant <project-id>=query-read,query-write] \
  [--expires-at <RFC3339> | --clear-expiry]
helix service-credential revoke <CREDENTIAL> [--yes]
```

Every subcommand also accepts `--workspace`.

## Subcommands

| Subcommand | Description |
| - | - |
| `create` | Create a credential and print its secret once. |
| `list` | List credentials owned by a workspace. The default when no subcommand is given. |
| `get` | Show one credential. Its secret is never returned. |
| `update` | Change the name, expiry, or project grants without rotating the secret. |
| `revoke` | Revoke a credential. |

## Arguments

| Argument | Description |
| - | - |
| `CREDENTIAL` | Credential ID or name to act on with `get`, `update`, or `revoke`. Required. |

## Options

| Flag | Description | Default |
| - | - | - |
| `--workspace <WORKSPACE>` | Owning workspace ID, slug, or name. | Linked workspace, then the only workspace |
| `--name <NAME>` | Credential name. Required for `create`; renames on `update`. | — |
| `--grant <PROJECT_ID>=<PERMISSIONS>` | Project grant, repeatable. `create` needs at least one; on `update`, any `--grant` replaces all existing grants. | — |
| `--expires-at <RFC3339>` | Expiry time for `create` or `update`. | No expiry |
| `--clear-expiry` | `update`: remove the expiry. Conflicts with `--expires-at`. | Off |
| `-y`, `--yes` | `revoke`: skip the confirmation prompt. Required without a terminal or with `--json`. | Off |
| `--json` | Print the result as JSON on stdout and never prompt. | Off |

## Behavior

* The workspace resolves as described in [Cloud resource resolution](/cli/command-reference#cloud-resource-resolution).
* Each grant is project-scoped and must name a project ID inside the owning workspace.
* Available grants are `project-read`, `project-write`, `query-read`, and `query-write`, comma-separated; write requires its matching read.
* Each project may appear in only one `--grant`, and a grant cannot repeat a permission.
* Creation prints the secret once on stdout. With `--json`, the full create response, including the secret, is printed instead. Updates never reveal or rotate it.
* `update` needs at least one of `--name`, `--grant`, `--expires-at`, or `--clear-expiry`.
* `revoke` asks for confirmation in a terminal. Without one, or with `--json`, it fails before any request unless you pass `--yes`.
* Service credentials authenticate headless HTTP API calls and the unified MCP endpoint at `https://mcp.helix-db.com/mcp`.
* MCP exposes only the query and customer administration tools their project grants allow. These sessions do not get Cloud discovery or observability tools.
* They are never a CLI login method and the CLI never persists them.

## Examples

```bash theme={null}
# Create a read-only credential for one project, expiring at the end of the year
helix service-credential create --name ci-reader \
  --grant <project-id>=project-read,query-read --expires-at 2026-12-31T23:59:59Z

# Allow the credential to write queries too (replaces all grants)
helix service-credential update ci-reader \
  --grant <project-id>=project-read,query-read,query-write

# Revoke it without a prompt
helix service-credential revoke ci-reader --yes
```

## Related

* [`helix auth`](/cli/command-reference/auth) — the WorkOS login used to manage credentials.
* [`helix workspace`](/cli/command-reference/workspace) — list your workspaces.
* [`helix project`](/cli/command-reference/project) — find the project IDs to grant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.