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

# Manage service account tokens for CI

> Give each CI integration its own Orka service account, track when its token expires, and rotate or revoke tokens without breaking pipelines.

CI pipelines should authenticate to Orka with service account tokens, not the personal tokens from `orka login`, which expire after an hour. [Understanding Orka credentials](https://docs.macstadium.com/orka/orka-cluster-access/understanding-orka-credentials.md) explains the difference. This page covers looking after service account tokens over time: scoping them, tracking when they expire, rotating them, and revoking them.

## Use one service account per integration

Create a service account for each CI system or pipeline group, such as `sa-jenkins` or `sa-gha-ios`, instead of sharing one across everything. Then you can:

* Rotate or revoke one integration's access without touching the others.
* Limit each one to the namespaces it needs. A service account gets access to namespaces through role bindings, so bind each one only where its pipelines deploy VMs. See [How access works in Orka](https://docs.macstadium.com/orka/orka-cluster-access/how-access-works.md).

## Track when each token expires

`orka sa token` issues a token that lasts one year by default, or the lifetime you request with `--duration`. Orka can return a token with a shorter or longer lifetime than you asked for, and it doesn't keep a copy of tokens that expire. You can't look up the expiry later by service account name.

Record the expiry when you create the token, for example in your secret manager or as a calendar reminder a few weeks ahead. To read it from a token you already have, decode the token's `exp` claim:

```bash theme={null}
python3 -c 'import base64,json,sys,datetime; p=sys.argv[1].split(".")[1]; p+="="*(-len(p)%4); e=json.loads(base64.urlsafe_b64decode(p)).get("exp"); print(datetime.datetime.fromtimestamp(e, datetime.timezone.utc) if e else "no expiration")' "$ORKA_TOKEN"
```

This prints the expiry in UTC. A token created with `--no-expiration` has no `exp` claim, so it prints `no expiration`.

## Rotate before a token expires

1. Create a new token for the same service account:

   ```bash theme={null}
   orka sa token <SERVICE_ACCOUNT_NAME>
   ```

2. Replace the token in your CI system's secret store, such as a GitHub Actions secret, a Jenkins credential, or a GitLab CI/CD variable.

3. Run a job to confirm the new token works.

Creating a new token doesn't invalidate the old one. The old token keeps working until it expires, so there's no gap while you swap them.

## Choose expiring tokens unless you need otherwise

A token created with `--no-expiration` never breaks a pipeline on a date, but it also keeps working indefinitely if it leaks. Use one when your setup requires it, or when you have a way to revoke it quickly. Otherwise, use an expiring token and rotate it on a schedule.

## Revoke access

Deleting a service account invalidates every token issued for it. To cut off a token before it expires, such as one that leaked:

1. Note which namespaces the service account can access. Deleting it removes it from the namespaces' dev role bindings, but not from admin role bindings.

2. If the service account has the admin role, revoke it first, or an account you recreate with the same name gets admin access back through the old binding:

   ```bash theme={null}
   orka rbac remove-subject --role admin --serviceaccount <SA_NAMESPACE>:<SERVICE_ACCOUNT_NAME>
   ```

3. Delete the service account: `orka sa delete <SERVICE_ACCOUNT_NAME>`.

4. Create it again and add it back to the namespaces it needs.

5. Issue a new token to each integration that uses it.

This is where one service account per integration pays off: revoking one leaked token only interrupts the pipelines that shared its account.

## Related pages

* [Understanding Orka credentials](https://docs.macstadium.com/orka/orka-cluster-access/understanding-orka-credentials.md)
* [Manage Orka service accounts for CI/CD](https://docs.macstadium.com/orka/orka-cluster-access/orka-cluster-manage-service-accounts.md)
* [How access works in Orka](https://docs.macstadium.com/orka/orka-cluster-access/how-access-works.md)


## Related topics

- [Manage Orka service accounts for CI/CD](https://docs.macstadium.com/orka/orka-cluster-access/orka-cluster-manage-service-accounts.md)
- [Orka CI/CD integrations quick start guide](https://docs.macstadium.com/orka/quick-start-guides/cicd-integrations-quick-start.md)
- [Cluster Access Management: Overview](https://docs.macstadium.com/orka/orka-cluster-access/cluster-access-management-overview.md)
- [Packer plugin for automated Orka image builds](https://docs.macstadium.com/orka/orka-devops-integrations/packer.md)
- [Post-migration tasks after upgrading Orka 2.4.x to 3.0.0](https://docs.macstadium.com/orka/orka-cluster-migration-from-24-3x/24x-to-300-after-the-migration.md)


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