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

# Service Accounts

> Use service accounts for passwordless CI/CD secret injection.

Service accounts provide machine identity for CI/CD pipelines. Unlike API keys, service accounts don't require your master password — a single `RELIC_SERVICE_TOKEN` environment variable is all you need.

## How It Works

Each service account has its own RSA key pair. The project key is wrapped with the service account's public key, and the private key is encrypted with a token-derived key using HKDF-SHA256. At runtime, the CLI derives the decryption key from the service token, decrypts the private key, unwraps the project key, and decrypts your secrets — all in a single HTTP call.

The server never sees the raw token or any plaintext keys.

## Creating a Service Account

Service accounts are created through the CLI. You need to be the project owner and have a Pro plan.

```bash theme={null}
relic service-account create --name "github-deploy"
```

With OIDC trust policy for GitHub Actions:

```bash theme={null}
relic service-account create --name "github-deploy" --github myorg/myrepo --branch main
```

Options:

| Flag | Required | Description |
| - | - | - |
| `-n, --name` | Yes | A descriptive name for the service account |
| `-p, --project` | No | Project ID (defaults to `relic.toml` or `RELIC_PROJECT_ID`) |
| `--expires-in` | No | Expiration in days (max 365) |
| `--github` | No | Enable OIDC for GitHub Actions (format: `org/repo`) |
| `--gitlab` | No | Enable OIDC for GitLab CI (format: `group/project`) |
| `--branch` | No | Branch restriction for OIDC (default: `*` for all branches) |

The CLI will output a service token that is shown **once**. Store it immediately in your CI provider's secret storage.

```
  Service Token (shown once):

  rsk_a1b2c3d4e5f6...

  Store this token in your CI provider's secret storage.
  Set it as RELIC_SERVICE_TOKEN in your pipeline environment.
```

## Using in CI/CD

Set `RELIC_SERVICE_TOKEN` in your pipeline environment, then run as usual:

```bash theme={null}
relic run -e production -- npm run deploy
```

No `RELIC_PASSWORD` or `RELIC_API_KEY` needed. The service token handles both authentication and decryption.

### GitHub Actions

```yaml theme={null}
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install Relic
        run: bun add -g relic

      - name: Deploy with secrets
        env:
          RELIC_SERVICE_TOKEN: ${{ secrets.RELIC_SERVICE_TOKEN }}
        run: relic run -e production -- npm run deploy
```

### GitLab CI

```yaml theme={null}
deploy:
  stage: deploy
  image: oven/bun:latest
  script:
    - bun add -g relic
    - relic run -e production -- npm run deploy
  variables:
    RELIC_SERVICE_TOKEN: $RELIC_SERVICE_TOKEN
```

## Managing Service Accounts

### List

```bash theme={null}
relic service-account list --project <project-id>
```

Shows all service accounts for a project with their status, expiry, and last usage time. Collaborators can also list service accounts.

### Revoke

```bash theme={null}
relic service-account revoke --name "github-deploy" --project <project-id>
```

Revocation is immediate. Any pipeline using the revoked token will fail on the next run. Only the project owner can revoke service accounts.

## Limits

* Maximum **5 active** service accounts per project
* Maximum expiration of **365 days**
* Expired and revoked accounts don't count toward the limit
* Requires a **Pro plan**

## Service Accounts vs API Keys

| | Service Account | API Key |
| - | - | - |
| Env vars needed | `RELIC_SERVICE_TOKEN` | `RELIC_API_KEY` + `RELIC_PASSWORD` |
| HTTP calls | 1 | 2 |
| Master password in CI | No | Yes |
| Scoped to | One project | Any project (or one) |
| Key management | Own RSA key pair | Uses owner's keys |

<Note>
  Using `RELIC_API_KEY` with `RELIC_PASSWORD` in CI is deprecated. Migrate to service accounts for
  better security and simpler configuration.
</Note>

## OIDC Trust Policies

Service accounts can be hardened with OIDC trust policies, which verify the CI platform's identity before allowing access. When configured, the service token only works when paired with a valid OIDC token from the trusted provider.

See the [OIDC Trust Policies](/guides/oidc) guide for setup instructions.

## Key Rotation

When a project key is rotated (e.g. after revoking a collaborator's share with rotation), active service accounts are automatically re-wrapped with the new key. No action is needed on your part — existing service tokens continue to work.

## Security Considerations

<Warning>
  Store `RELIC_SERVICE_TOKEN` in your CI provider's secret storage. Never hardcode it in pipeline
  files or commit it to your repository.
</Warning>

* Each service account is scoped to exactly one project
* The service token is shown once at creation time and cannot be retrieved later
* Service accounts can be revoked instantly from the CLI
* All service account usage is logged in the [audit trail](/configuration/audit-logs)
* Projects with active service accounts cannot be archived — revoke them first
* The raw token never reaches the Relic server; only a SHA-256 hash is stored


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