# Credentials & Rotation

The credentials your integration holds, how your administrators read them, and how to replace each one — on your schedule, or at once when one may have leaked.

## Overview

- Your **server** holds your tenant's API key and secret, or a server credential's private key: they sign the calls made for your tenant ([Authentication](https://docs.aureahub.com/docs/authentication.md)).
- Your **users** hold their own access and refresh tokens, given at sign-in: never your tenant's credentials.
- Your tenant's administrators manage the credentials with their own access token. Reading and rotating them is for the `owner`, `tenantadmin`, `non_signing_admin` and `security_admin` roles ([Roles](https://docs.aureahub.com/docs/authentication.md)).

## Your Credentials

- **API key** — `ak_live_` and 64 hex characters, sent as `x-tenant-api-key`: it names your tenant. One per tenant, for test networks and production alike: `live` is part of the format, not the environment ([Environments › Test and Live](https://docs.aureahub.com/docs/guide-environments.md)).
- **API secret** — `as_` and 64 hex characters: the key of the HMAC signature (`x-signature`). Never sent. One per tenant.
- **Server credentials** — key pairs your server makes, whose public keys you register; your server signs with a short-lived token instead of the HMAC headers. Up to 10 active at once, each with its own role, IP allow-list and expiry ([Server Credentials](https://docs.aureahub.com/docs/guide-server-credentials.md)). A tenant on the institutional security profile signs with them.
- **Webhook secrets** — one per webhook endpoint, and one per environment webhook: they sign the events Aurea posts to you, and your server checks them ([Webhooks & Events](https://docs.aureahub.com/docs/guide-events.md)).
- **Agent Payments keys** — the keys of your payment agents, where your tenant has Agent Payments ([Agent Payments](https://docs.aureahub.com/docs/agentic-payments.md)).

## Getting Them

> Tip: **No tenant yet?** Ask for a sandbox tenant: you receive its API key and secret and your first administrator's account. We reply within one business day.
>
> [Request sandbox access](https://access.aureahub.com/login?request=build&source=sandbox)

1. When Aurea creates your tenant, you receive its **API key and secret** and the account of your first administrator. The same key and secret work on test networks and in production ([Environments › Test and Live](https://docs.aureahub.com/docs/guide-environments.md)).
2. Your server signs that administrator in ([Login](https://docs.aureahub.com/docs/auth-login.md)) and gets an access token. Your tenant's id is the token's `tenantId` claim, and the `id` of [Get Your Tenant](https://docs.aureahub.com/docs/tenant-info.md).
3. From then on, an administrator reads the credentials whenever needed: [Get the API Key](https://docs.aureahub.com/docs/admin-tenants-apikey.md) and [Get the API Secret](https://docs.aureahub.com/docs/admin-tenants-secret.md).
4. Give your other administrators their own accounts, each with its role ([Create User](https://docs.aureahub.com/docs/users-create.md)): every action is then written with who did it.

```bash
# An administrator's access token, for your own tenant
curl https://api.aureahub.com/v1/admin/tenants/$TENANT_ID/api-secret \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"
# { "apiSecret": "as_…" }
```

## Keeping Them

- Keep the API secret and server credentials' private keys in your server's secret store. Never put them in an app, a browser, a repository or a log.
- Give each server its own server credential, with the narrowest role it needs and an IP allow-list: you can then revoke one without touching the others.
- Your administrators' sign-in protects the credentials: give them a second factor where your tenant has it ([Two-Factor Sign-In](https://docs.aureahub.com/docs/guide-two-factor.md)).

## Rotating the API Secret or Key

[Rotate the API Secret](https://docs.aureahub.com/docs/admin-tenants-rotatesecret.md) and [Rotate the API Key](https://docs.aureahub.com/docs/admin-tenants-rotatekey.md) answer the new value. **The old one stops working at once**: until your servers have the new value, their signed requests answer `401` `Invalid signature`.

1. Make sure every server reads the value from configuration it can reload, and that a signed request refused with `401` is retried after a reload.
2. Rotate, and store the new value in your secret store at once. You can read it again with Get the API Secret or Get the API Key.
3. Reload your servers, and check that signed calls succeed — [Get Public Config](https://docs.aureahub.com/docs/tenant-public.md) is a harmless one.

- Rotating one never changes the other, the server credentials or the webhook secrets.
- **Your tenant's quorum.** Where your tenant's quorum holds administrators' actions, a rotation answers `202` `{ "state": "awaiting_quorum", "requestId" }`; once another administrator approves it, whoever asked reads the new value once ([Your Tenant's Quorum](https://docs.aureahub.com/docs/guide-tenant-quorum.md)).
- Every rotation is written to your tenant's [audit trail](https://docs.aureahub.com/docs/audit-events.md) [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md).

## Rotating Without a Gap

To replace your server's signing key with no refused request, sign with server credentials: two can be active at once.

1. Make a new key pair on your server and register its public key ([Register a Credential](https://docs.aureahub.com/docs/server-credential-create.md)).
2. Move your servers to the new credential. Both work meanwhile.
3. Revoke the old one ([Revoke a Credential](https://docs.aureahub.com/docs/server-credential-revoke.md)): its tokens are refused from then on, and your endpoints that name `server_credential.revoked` are told.

Once all your servers sign with server credentials, the API secret is no longer used by them: keep it stored, and rotate it on your schedule.

## Webhook Secrets

A webhook endpoint's secret ([Give an Endpoint a New Secret](https://docs.aureahub.com/docs/webhook-endpoint-rotate.md)) and an environment webhook's secret ([Replace a Webhook's Secret](https://docs.aureahub.com/docs/tenant-webhook-rotate.md)) are replaced the same way: the new one is answered once and signs every delivery from then on, retries included. A delivery your server refuses meanwhile is retried, so put the new secret in place within a few minutes.

## If a Secret Leaks

1. Rotate it at once — the API secret, the webhook secret, or revoke the server credential.
2. Read your [audit trail](https://docs.aureahub.com/docs/audit-events.md) for what was done with it, and freeze what must not move while you check ([Freezes & Quarantines](https://docs.aureahub.com/docs/guide-freezes.md)).
3. Tell your Aurea contact.

---

Web version: https://docs.aureahub.com/#guide-credentials