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

# Service Accounts

> Create non-human identities for applications, CI/CD pipelines, and services to authenticate with Datum APIs

Service accounts give non-human workloads — CI/CD pipelines, backend services, and scripts — a stable cryptographic identity to call Datum APIs. They authenticate using RSA key pairs rather than shared passwords or long-lived user tokens.

## When to use service accounts

| Use case | Example |
| - | - |
| CI/CD pipelines | GitHub Actions deploying resources on every merge |
| Kubernetes workloads | A pod calling the Datum API using a projected secret |
| Backend services | A service authenticating as itself, not as a user |
| Local automation | Scripts that run without a browser-based login |

## Create a service account

The Cloud Portal offers two starting points. **CI/CD Pipeline** generates a credentials file to store as a secret in GitHub Actions, GitLab CI, or another pipeline, with setup instructions. **Service** gives a backend service or workload a stable identity to call Datum APIs, with credentials you mount as a Kubernetes Secret or environment variables.

![The Add a Service Account tab, with two cards: CI/CD Pipeline and Service, each with a Create a service account button](https://mintcdn.com/datum-4926dda5/Xc9AnQUL-oEENeSS/images/service-account-types.png?fit=max\&auto=format\&n=Xc9AnQUL-oEENeSS\&q=85\&s=c568a2dfab7b172a12e150a0d03073a7)

Choose the kind of service account to create

1. Open your project in the [Datum Cloud portal](https://cloud.datum.net).
2. Navigate to **Service Accounts** in the left sidebar.
3. Select **Create service account**.
4. Enter a lowercase name (e.g. `ci-deploy`) and an optional display name.

   ![Service account creation form](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=63d5a70deedcf2035fb889253c4766cb)
5. Select a key type:
   * **Datum-managed** — Datum generates an RSA key pair. The private key is shown **once** at creation time. Download it as a JSON credentials file before closing the wizard.
   * **User-managed** — You provide your own RSA public key in PEM format. Datum stores only the public key and never sees your private key.

     ![Key type selection](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image-1.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=1c7557d696c6b4e37dcd9c0beb6e5236)
6. Select **Create**. Once the account's identity email is provisioned, your credentials are ready.

   ![Service account created, credentials available to download](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image-2.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=db81205c074e3d3eb57a8a73c109f65b)

> [!NOTE]
>
> For datum-managed keys, the private key is only displayed once. Download the credentials file before closing the wizard — it cannot be recovered later.

## Manage keys

Open a service account and navigate to the **Keys** tab to add or revoke keys.

* **Add a key** — create an additional datum-managed or user-managed key at any time.
* **Revoke a key** — immediately invalidates the key. Any tokens issued with it will stop working at expiry.

To rotate keys with zero downtime: add the new key, update your workloads to use it, then revoke the old key.

## Assign roles

Service accounts are IAM principals like any other member. Assign roles from the **Roles** tab on the account's detail page, or from **Settings → Members** in your project or organization.

![Policy Bindings form showing role assignments](https://mintcdn.com/datum-4926dda5/TEJDitxXSc4uEVSS/images/image-3.png?fit=max\&auto=format\&n=TEJDitxXSc4uEVSS\&q=85\&s=fd208ebf6322e8c8a4c68c75f9d7e4c0)

## Disable or delete an account

* **Disable** — suspends authentication without removing the account or its keys. Re-enable at any time from the **Overview** tab.
* **Delete** — permanently removes the account and revokes all associated keys. This cannot be undone.

## Using credentials

After creating a service account, you'll have a credentials file to use for authentication.

### Credentials file format

When you create a datum-managed key, Datum returns a JSON credentials file. For its fields, see [The credentials file](https://datum.net/docs/datumctl/auth/service-accounts.md#the-credentials-file).

**Treat this file like a password** — store it in a secrets manager and never commit it to source control.

### datumctl

Log in with the credentials file, then run commands as the service account:

```bash theme={null}
datumctl login --credentials /path/to/credentials.json
datumctl get organizations
```

Service-account login doesn't prompt you to pick a context, so pass `--organization` or `--project` on each command, or set a context. For custom environments and more, see [Service accounts in datumctl](https://datum.net/docs/datumctl/auth/service-accounts.md#log-in-with-a-credentials-file). For a pipeline, see [Automating datumctl in CI/CD](https://datum.net/docs/datumctl/cicd/automating.md).

### GitHub Actions

Store the contents of the credentials file as a repository or organization secret, such as `DATUM_SA_CREDENTIALS`, and pass it to the `datumctl` setup action. The action logs in as the service account, so later steps run `datumctl` without a login command. For the full workflow, see [GitHub Actions](https://datum.net/docs/datumctl/cicd/github-actions.md).

### Kubernetes

Create a Kubernetes secret from the credentials file:

```text theme={null}
kubectl create secret generic datum-credentials \
  --from-file=credentials.json=/path/to/credentials.json
```

Mount it into your pod, then log in with the mounted file before running `datumctl`:

```yaml theme={null}
volumeMounts:
  - name: datum-credentials
    mountPath: /var/secrets/datum
    readOnly: true
volumes:
  - name: datum-credentials
    secret:
      secretName: datum-credentials
```

```bash theme={null}
datumctl login --credentials /var/secrets/datum/credentials.json
```


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