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

# Managed role changes

> Rotate or revoke one managed database role without changing other profiles.

<Note>
  This capability is in preview and requires activation for your database. An
  unavailable target is refused before a new operation is created.
</Note>

The API key must belong to the current database owner and include the database
in its scope. Public profiles are `owner` (including migration access), `runtime`
and `readonly`. Internal Explorer access is not a public profile.

<Warning>
  Rotation and revocation close existing connections for the selected role. Open
  transactions on those connections roll back. Confirm this effect before sending
  the request. Other role profiles remain available.
</Warning>

## Create an operation

Send a stable `Idempotency-Key` header and this exact JSON body:

```json theme={null}
{
  "profile": "runtime",
  "kind": "rotate",
  "confirmDisconnect": true
}
```

Use `kind: "revoke"` to disable that login. Revoke preserves grants and data;
rotation does not reactivate a revoked profile. Do not send a password, physical
role name, database name, connection string or internal Explorer profile.

The response is `202` while pending or `201` when completed, with a `Location`
header pointing to the operation. It contains no credentials:

```json theme={null}
{
  "operationId": "22222222-2222-4222-8222-222222222222",
  "status": "pending",
  "profile": "runtime",
  "kind": "rotate",
  "credentialGeneration": 2
}
```

Retry the same intent with the same key. A different profile or kind on that key
is refused. An unknown result remains pending; it does not select another password
or undo a change. Explicit credential retrieval is unavailable for the selected
profile until completion. The separate credentials endpoint returns the current
credential after a completed rotation.

## Read or reconcile

`GET /api/v1/databases/{id}/role-changes/{operationId}` returns `200` with operation
metadata. It performs no native mutation or reconciliation.

To reconcile an uncertain outcome, send `POST` to that same operation URL with
exactly `{"confirmDisconnect": true}`. The server reuses the recorded input and
returns `202` pending or `200` completed. An already completed replay performs no
native operation. Completed remote work can be finalized while new mutations are
disabled; unfinished native work waits for mutation availability and an active database.
Stopped databases retain metadata and completed replay; they cannot reserve a new
role change or dispatch a native credential mutation.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | Invalid profile/kind, missing acknowledgement or idempotency key |
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
| 404 | `DATABASE_NOT_FOUND` | Database is not accessible to this key |
| 409 | `MANAGED_ROLE_CONFLICT` | Binding/intent changed, or operator reconciliation is required |
| 503 | `FEATURE_UNAVAILABLE` | Activation or the exact agent target capability is unavailable |
| 500 | `INTERNAL_ERROR` | Request failed; retry the same intent or inspect its existing operation |

All responses use `Cache-Control: no-store`. An unresolved operation prevents
owner reassignment until verified completion.


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