Rotate a credential's secret in place

Replaces the credential’s secret without recreating it, so clusters and other resources that reference it keep working. The supplied fields are probed against the provider first: a refused probe answers 200 with rotated: false and the probe’s code, message and hints, and the stored secret is left unchanged. The new value is then read against every cluster that uses the credential (its network, then its servers): a cluster it cannot see refuses the rotation with code foreign_project, one that could not be checked with cluster_unreachable, both listed in unreachable_clusters; set force to save anyway. Connection settings cannot be rotated. Requires credentials.write; a credential pinned to another project answers 404.

PUT /api/v1/org/credentials/{credential_id}

Rotate a credential's secret in place

Python

import requests

url = "https://platform.ankra.app/api/v1/org/credentials/{credential_id}"

payload = { "payload": {} }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

200

{
  "rotated": true,
  "result": {
    "ok": true,
    "code": "<string>",
    "message": "<string>",
    "hints": [
      "<string>"
    ]
  },
  "forced": true,
  "unreachable_clusters": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "code": "foreign_project",
      "reason": "<string>"
    }
  ],
  "unverified_clusters": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "code": "foreign_project",
      "reason": "<string>"
    }
  ],
  "propagation": {
    "rotation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "revision": 123,
    "rotated_at": "2023-11-07T05:31:56Z",
    "verified_at": "2023-11-07T05:31:56Z",
    "safe_to_revoke": true,
    "blocking_clusters": [
      {
        "cluster_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "cluster_name": "<string>",
        "state": "queued",
        "reason": "<string>",
        "remedy": "<string>"
      }
    ],
    "clusters": [
      {
        "cluster_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "cluster_name": "<string>",
        "coverage": "covered",
        "state": "queued",
        "reason": "<string>",
        "remedy": "<string>",
        "forced": true,
        "operation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "rotated_at": "2023-11-07T05:31:56Z",
        "dispatched_at": "2023-11-07T05:31:56Z",
        "rendered_at": "2023-11-07T05:31:56Z"
      }
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

authorization · string | null

x-ankra-organisation-id · string | null

Path Parameters

credential_id · string<uuid4> · required

Body

application/json

payload · Payload · object · required

The fresh secret fields for the credential's provider, for example api_token for Hetzner, UpCloud and DigitalOcean, token_secret for Proxmox VE, access_token for HPE Morpheus, secret_key for Scaleway, application_key/application_secret/consumer_key for OVHcloud, client_secret for Azure, and access_key_id with secret_access_key for a Hetzner credential's Object Storage keys. Connection settings (api_url, project_id, tls_insecure, ...) cannot be rotated.

Show child attributes

force · boolean · default: false

Save the new value even though a cluster that uses the credential failed the reach check ("rotate anyway"). The answer still lists those clusters in unreachable_clusters, and the audit record notes the override. It never overrides a refused connection test or a refused Object Storage key pair.

Response

200

application/json

The probe ran: rotated says whether the stored secret was replaced

rotated · boolean · required

True when the supplied secret passed the provider probe and replaced the stored one; false when the probe failed and nothing was changed.

result · Result · object · required

Show child attributes

forced · boolean · required

True when the new value was saved with force although a cluster in unreachable_clusters failed the reach check.

unreachable_clusters · RotateCredentialCluster · object[] · required

The clusters using this credential that the new value failed the reach check for: foreign_project when the provider answered 403 or 404 for every object the cluster recorded as its own (its network, then its servers), cluster_unreachable when the provider could not be asked. Any entry refuses the rotation unless force is set.

Show child attributes

unverified_clusters · RotateCredentialCluster · object[] · required

The clusters using this credential that were not checked: no recorded network or server, a provider without a reach check, or a cluster being deleted. They never refuse a rotation.

Show child attributes

propagation · CredentialRotationPropagation · object

Present when the rotation was recorded: every linked cluster in its initial state. Follow it with GET /api/v1/org/credentials/{credential_id}/propagation.

Show child attributes