Saved Credentials API¶

Create, rotate and delete a runtime plane's saved credentials from a script. The portal's Credentials tab does the same, and encrypts secrets for you; use this API for automation, or on a self-managed runtime plane.

Paths below are relative to your Runtime Manager API. {planeId} is the runtime plane's ID, and {id} a credential's id. Administrators only.

Endpoints¶

Credential types¶

The secret is write-only, and always encrypted¶

• Send the secret encrypted with the runtime plane's active key, never in plain text. Fetch the key from GET /api/v1/rsa-keys/runtime-planes/{planeId}/active.
• Send keyFingerprint: the lowercase hex SHA-256 of that public key's X.509 DER bytes, so Trust3 can confirm you used the current key.
• Trust3 never decrypts the secret; only the runtime plane can. A secret not encrypted with the plane's current key is rejected.
• No response ever returns the secret, encrypted or not.

On a runtime plane with an external secret store, send the key name instead, and no keyFingerprint.

Create a credential¶

POST /runtime-plane/{planeId}/credentials

1
2
3
4
5
6
7

{
  "name": "prod-sp",
  "type": "entra_sp",
  "publicFields": { "tenantId": "<directory (tenant) ID>", "clientId": "<application (client) ID>" },
  "secret": { "clientSecret": "<the client secret, encrypted with the plane's key>" },
  "keyFingerprint": "<fingerprint of the key you encrypted with>"
}

• name — up to 255 characters, unique on the runtime plane ignoring case, with no leading or trailing spaces.
• publicFields — the type's non-secret fields. Never put the secret here.
• secret — exactly one entry, the type's secret field.

The response is 201 with the credential, without the secret. version starts at 1.

Edit and rotate a credential¶

PUT /runtime-plane/{planeId}/credentials/{id}

• Send the full name and publicFields.
• Leave secret out to keep the stored secret. Send secret and keyFingerprint only to replace it.
• The type, and an entra_sp credential's tenantId and clientId, cannot change. Create a new credential instead.
• version goes up by one whenever the secret or a field changes. A rename alone does not change it.
• A new version is copied into every collector that uses the credential, one at a time, and each restarts once. The response lists every collector with its state.

If the request times out, the change is saved. Do not change the credential again; read it to see each collector's state, and retry the ones that are not updated.

Preview the restart first¶

Send the same body you would send to the PUT to POST /runtime-plane/{planeId}/credentials/{id}/restart-preview. Nothing is saved, and the request is checked exactly as the PUT checks it.

1
2
3
4
5
6
7
8
9

{
  "credentialId": 17,
  "version": 3,
  "valuesChange": true,
  "changedFields": ["clientSecret"],
  "restarts": [ { "applicationId": 40, "applicationName": "collector-prod", "groups": ["databricks", "azure"] } ],
  "notRestarted": [ { "applicationId": 41, "applicationName": "collector-dev", "groups": ["azure"], "reason": "the collector is stopped, so it is not updated now. Booting it applies the new version" } ],
  "warnings": []
}

valuesChange: false means the edit changes nothing the collectors use, for example a rename.

List and view¶

• Both the list and a single credential show summary, for example prod-sp v4 · 18 of 20 applied · 2 pending.
• A single credential shows usages: each collector that uses it, with state and stateText. States are APPLIED, PENDING, NOT_APPLIED and NOT_UPDATED — see What the states mean. A NOT_UPDATED usage carries copyError.
• keyRevoked: true means the plane's encryption key was rotated after the secret was entered, so the plane can no longer read it. Send the secret again in a PUT, encrypted with the current key.
• The runtime plane's details show "capabilities": ["credentials"] where this API manages the plane's saved credentials.

Use a credential in a connection¶

Set the section's *.credential-ref field to the credential's id, as text (for example "17"). Leave it "" to enter the fields directly.

On save, Trust3 writes the credential's values into the connection's fields whatever the request sent for them, so you can leave them out. Connector create, update and import responses carry a warnings list when Trust3 changed something instead of refusing it — for example CREDENTIAL_REFERENCE_CLEARED when an import cleared a credential that does not exist on the target runtime plane.

Planes with an external secret store¶

1
2
3
4
5
6

{
  "name": "prod-sp",
  "type": "entra_sp",
  "publicFields": { "tenantId": "<directory (tenant) ID>", "clientId": "<application (client) ID>" },
  "secret": { "clientSecret": "collector-entra-secret" }
}

• A key name is 1 to 253 letters, digits, ., _ and -; on Azure Key Vault, 1 to 127 letters, digits and -.
• A value that looks like an encrypted secret or like the secret itself (dapi…, dose…, sk-…, sk-ant-…) is rejected, as is a keyFingerprint.
• Responses include secretKeyName.
• After you change the value in the store and keep the key name, call POST /runtime-plane/{planeId}/credentials/{id}/restart to restart every collector that uses it.

Errors¶