# Naming, reuse, rotation, and deletion

> Keep credentials least-privilege and reusable, rotate them without downtime, check what depends on one, and delete it safely.

Everything on this page is what happens after the credential works. It is also
what makes the difference between an integration you can hand over and one
nobody dares touch.

## Outcome

Any credential in your organization can be found, rotated, and removed by
someone who did not create it.

## Name it so revoking the right one is obvious

Name after the integration, not the technology. *Stripe webhook ingest* beats
*API key 2*.

| Thing | A good name | Why |
|---|---|---|
| Service account | `Stripe webhook ingest` | Names the sender, so revoking the right one is unambiguous. |
| Outbound connector | `Shopify — orders read` | Names the service and what the credential is allowed to do. |
| Inbound connector | `Warehouse — order webhooks` | Names the source system and what it sends. |
| API Spec | `Shopify Admin 2026-01` | Names the API and its version, so a re-upload is a decision rather than a surprise. |

## Grant the narrowest scope that works

A service account borrows a member's permissions, and its scopes narrow that
further. Grant only what the integration does:

| Scope | Grants |
|---|---|
| `webhooks` | Sending data into Hodoflow through webhook requests. |
| `api_read` | Read-only access to workflows, runs, and warehouse records. |
| `api_write` | Any request that is not a read. |
| `embed` | Loading dashboards inside external sites through the embed element. |

A webhook sender needs `webhooks` and nothing else. Splitting one busy
credential into several narrow ones costs nothing and means an incident revokes
one integration instead of all of them.

Point **Run as** at whoever should own the integration long-term, not at
whoever happened to create it — deactivating that person changes what the
credential can reach.

## Reuse one connector rather than copying credentials

Credentials live on the connector, not inside a step, precisely so that one
edit re-credentials every workflow that uses it. Two connectors holding the
same key is two places to rotate and one place to forget.

Make a second connector when the *account* differs — separate keys for staging
and production, or a read-only key alongside a writing one — not when a second
workflow needs the same access.

## Rotate a service account secret without downtime

Rotation is two steps, so there is never a window where nothing works.

1. **Stage new secret** generates a second client ID and secret alongside the
   active pair. **Both pairs authenticate at once.** The staged values appear
   under **Client Credentials → Staged credentials** with a **Pending
   promotion** badge.
2. Update your integrations to the staged values and confirm they still work.
3. **Promote staged** makes the staged pair the active one. The previous pair
   stops working immediately.

**Restage new secret** replaces a staged pair you have not promoted yet — the
pair you overwrite stops working immediately, so only restage if nothing has
picked the staged values up.

## Rotate a connector credential

Connectors have no staging. Open the connector, type the new secret over the
blank field, and save; the change takes effect on the next call.

Where the provider allows two live keys, create the new key there first,
update the connector, then revoke the old key at the provider — that gives you
the same no-downtime shape.

## Find out what depends on it before you change anything

Every credential has a **Usage** view. Check it first.

| Thing | Usage shows |
|---|---|
| Service account | The workflow versions whose triggers authenticate with it. |
| Connector | The workflow versions that reference it, with **Open builder** on each row. |
| API Spec | The workflow steps bound to its operations. |
| Data model | Every dashboard widget and workflow that references it. |

## Turn one off safely

**Deactivate** a service account and it stops exchanging for tokens at all. It
is reversible with **Activate**, which makes it the right tool for a suspected
leak you are still investigating.

Deactivation is refused while an active workflow depends on the credential —
deactivate the workflow first.

## Delete

Deleting a service account is permanent, and any external system using it loses
access the moment you confirm. It is refused while workflow triggers still
reference it.

Deleting a connector is refused while anything still points at it, and offers
**View usage** so you can go reassign those steps first. The same is true of an
API Spec with bound steps.

The order that always works:

1. Open **Usage** and note everything listed.
2. Repoint or delete those steps and triggers.
3. Deactivate the credential and watch for a day, if you can afford to.
4. Delete.

## Common problems

**Deactivating is refused.** An active workflow still depends on it.
**Usage** names which; deactivate those workflows first.

**Deleting is refused even though Usage looks empty.** Usage lists workflow
*versions*, including inactive and draft ones. An old version still counts.

**I rotated and everything broke immediately.** **Promote staged** takes effect
at once. Promote only after the integrations are already using the staged
values.

**I cannot find where a key is used.** Search is per credential, through
**Usage**. If nothing lists it, nothing in Hodoflow is using it — but check
outside Hodoflow before deleting.

## Next step

[Connection and authentication
errors](/help/credentials-connections/connection-errors).