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

# Service accounts

> Why a shared integration should not run on a person's API key, what a service account is, and how its keys are created and stopped.

**A personal key leaves when its owner does.** Keys carry the permissions of the
person who made them, so if that person's access is removed — they change roles,
they leave — every integration riding on their key stops with them, usually at
the worst moment.

A **service account** is an identity that belongs to the account rather than to
a person. Give it its own keys, and nobody's departure takes your scheduled job
down.

## Use one for anything shared

| Use a service account             | Use your own key                   |
| --------------------------------- | ---------------------------------- |
| A scheduled job or automation     | Trying something out               |
| An internal tool your team shares | A script you run by hand           |
| Another platform calling us       | An assistant working alongside you |

The test is simple: **if the thing would still need to run after you left, it
should not be on your key.**

## What it can do

A service account is not a way around permissions. It rides the same machinery
everyone else does:

* It joins the account as a **Member**, which is the least it can be and still
  use the API at all.
* Anything beyond that is granted to it **one permission at a time**, exactly
  the way you would grant a permission to a person.
* Actions that publish, spend, delete or hand out access still stop for a human
  decision, whoever — or whatever — is asking. See [Who can use the
  API](/permissions).

So a service account can never quietly do more than the permissions someone
deliberately gave it.

## Creating its keys

Service accounts appear in the **Holder** list when you create a key:

<Steps>
  <Step title="Open Settings → API & MCP and choose New key">
    The same page and the same dialog you use for your own keys.
  </Step>

  <Step title="Pick the service account as the Holder">
    The dialog says it plainly — *use a service account for an integration, so
    the key survives someone leaving.* If the list shows only people, your
    account has no service account yet.
  </Step>

  <Step title="Choose its reach and expiry">
    Narrow it to a single workspace if the integration only touches one, and
    set an expiry if the work is temporary. Both are easier to decide now than
    to tighten later.
  </Step>

  <Step title="Copy the key once">
    It is shown once and never again, exactly like a personal key. Put it
    straight into the secret store your integration reads.
  </Step>
</Steps>

Its keys then sit in the same list as everyone else's, with the service account
named in the **Holder** column, so you can always see what is running under it.

<Note>
  Setting a service account up is an account **Owner's** decision, not something
  a member does for themselves — the same posture as adding a person to the
  account.
</Note>

## Stopping one

Two levers, and they are different sizes:

* **Revoke one key.** Stops that one integration on its very next call. The
  service account's other keys keep working.
* **Deactivate the service account.** Stops every key it holds. This is
  permanent — a deactivated identity is never brought back, because resurrecting
  one would quietly re-arm every key it ever had. If you need it again, create a
  new one.

Nothing is ever deleted, which is the point: the record of what that identity
did stays readable after it stops.

## Good habits

* **One service account per system**, not one for everything. Then stopping a
  vendor does not stop your own jobs.
* **Give it the narrowest reach that works** — a single workspace if that is all
  it touches.
* **Name it after the thing that uses it**, so a year from now the keys list
  still explains itself.
* **Never share its key with a person.** If someone needs to try something, they
  should use their own key.