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

# Service accounts

> Machine credentials, RSA keys and permission scopes.

A service account is the identity your server uses to call the API. It holds an API key, an API
secret, the RSA public key your signatures are verified against, and a set of permissions that
decide which operations it may perform.

Service accounts are created and managed from the **Developer Hub** in your [dashboard](https://dashboard.stablemint.net/). They cannot
be created through the public API — a service account cannot mint, revoke or re-scope another
service account, by design.

## You generate the key pair, not us

StableMint never holds your private key. You generate an RSA key pair, upload the **public** half
when you create the service account, and keep the private half on your own infrastructure.

```bash theme={null}
# Generate a 2048-bit RSA key pair
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out stablemint-private.pem

# Derive the public key to upload
openssl rsa -in stablemint-private.pem -pubout -out stablemint-public.pem
```

Upload the contents of `stablemint-public.pem` when creating the service account. Store
`stablemint-private.pem` in your secret manager — if you lose it, you cannot sign requests and must
create a new service account with a fresh key.

<Warning>
  Treat the **API secret** as a credential of the same weight as the private key. It is part of
  every canonical string you sign, so anyone holding both it and your private key can sign requests
  as you. If it is exposed, revoke the service account and create a new one.
</Warning>

## Limits

<CardGroup cols={2}>
  <Card title="Five per partner" icon="hashtag">
    You may hold up to five active service accounts at a time.
  </Card>

  <Card title="Empty by default" icon="lock">
    A new service account has no permissions. Grant only what it needs.
  </Card>
</CardGroup>

## Permissions

Permissions are granted per service account from the dashboard, and they are what separates a
service account that can read from one that can move money. A call made without the permission it
needs returns `403` — a valid signature is not enough on its own.

<Note>
  **A service account cannot widen its own access.** Reading and changing permissions requires a
  signed-in dashboard user; those endpoints reject signed service-account requests. This is what
  stops a leaked credential from escalating itself.
</Note>

## Rotating without downtime

Because you can hold five service accounts at once, rotation does not require a maintenance window:

<Steps>
  <Step title="Create a second service account">
    Generate a new key pair and register the new public key. Grant it the same permissions as the
    one you are replacing.
  </Step>

  <Step title="Deploy the new credentials">
    Roll the new API key, API secret and private key out to your services. Both accounts are valid
    at once, so there is no cutover moment.
  </Step>

  <Step title="Confirm traffic has moved">
    Check that calls are arriving under the new API key before going further.
  </Step>

  <Step title="Revoke the old account">
    Delete the previous service account from the [Developer Hub](https://dashboard.stablemint.net/). Signatures made with its key stop
    verifying immediately.
  </Step>
</Steps>

## Sandbox and production are separate

Sandbox and production credentials are issued independently and are not interchangeable. A sandbox
service account cannot call production, and vice versa.

<Warning>
  Sandbox and production API keys currently share the same prefix, so the key string alone does not
  tell you which environment it belongs to. Keep them in separate secret stores and key your
  configuration off the base URL rather than off the credential.
</Warning>

## Next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    How to sign a request with these credentials.
  </Card>

  <Card title="Sandbox" icon="flask" href="/guides/sandbox">
    Exercise the full flow without moving real money.
  </Card>
</CardGroup>