Attach a credential to a principal.

POST

/iam/principals/{id}/credentials

curl --request POST \
  --url https://example.com/iam/principals/example/credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "publicKey": "example", "type": "example" }'

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Principal id.

Request Body^required

Request body for POST /iam/principals/:id/credentials.

credential_type is kept as a raw String so that Axum’s JSON extractor never rejects the request before the handler runs. An unknown value produces the project’s {"error":{"code":"INVALID_VALUE",...}} envelope rather than Axum’s default 422 body. The handler parses the string into [CredentialType] explicitly and returns the structured error on failure.

Media typeapplication/json

Request body for POST /iam/principals/:id/credentials.

credential_type is kept as a raw String so that Axum’s JSON extractor never rejects the request before the handler runs. An unknown value produces the project’s {"error":{"code":"INVALID_VALUE",...}} envelope rather than Axum’s default 422 body. The handler parses the string into [CredentialType] explicitly and returns the structured error on failure.

object

publicKey

SSH public key in OpenSSH format (for type "ssh").

string | null

type

required

Credential type string as received on the wire, e.g. "ssh".

Kept as String (not CredentialType) so that unknown values are rejected with the project error envelope, not Axum’s default 422 body.

string

Example^generated

{
  "publicKey": "example",
  "type": "example"
}

Responses

201

Credential details returned to the API caller.

Sensitive fields (credential_data, secret_hash) are never included; only public metadata is surfaced (fingerprint for SSH, username for password).

Media typeapplication/json

Credential details returned to the API caller.

Sensitive fields (credential_data, secret_hash) are never included; only public metadata is surfaced (fingerprint for SSH, username for password).

object

createdAt

required

ISO 8601 creation timestamp.

string

id

required

Credential UUID.

string

metadata

Non-sensitive metadata from the credential (e.g., username, fingerprint).

type

required

Credential kind.

Any of:

unknown

A credential type this server version understands.

One of:

string

Password credential (username + hashed secret).

string

Allowed value: password

string

SSH public key credential.

string

Allowed value: ssh

string

One-time setup/password-reset token.

string

Allowed value: setup_token

string

A credential type string from the DB that this server version does not recognise. Preserved as-is so the API response reflects reality.

string

updatedAt

required

ISO 8601 last-modified timestamp.

string

Example

{
  "type": "password"
}

default

Structured error envelope (SPEC-DATA-0006): {"errors": [{"scope", "target", "code", "message"}, ...]}.

Media typeapplication/json

The top-level response body. Wraps a non-empty list of [ErrorEntry].

object

errors

required

The error entries making up the envelope. Always non-empty.

Array<object>

One entry in the error envelope.

Carries an anchoring [ErrorScope], an optional target that disambiguates within the scope, a stable SCREAMING_SNAKE_CASE code, and a human-readable English message. See SPEC-DATA-0006 for the full envelope contract.

object

code

required

Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.

string

location

Any of:

object

HFX source location for a [DataError::HfxCompileError] entry.

Emitted as the extra location field on the entry JSON when present, per SPEC-UI-0043. The line/column are 1-based. The frame is the offending source line extracted verbatim from the input.

object

column

required

1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.

integer format: uint32

frame

The offending source line text, when available.

string | null

line

required

1-based line number within the source text.

integer format: uint32

null

null

message

required

Server-authored English message. Not part of the API contract; may change across releases without notice.

string

rule

The key of the ValidationRule that failed, when the code is RULE_FAILED. None for all other codes.

Skipped during serialization when absent so it does not appear on unrelated entries (same pattern as location).

Documented here as a plain string (#[schemars(with = "...")]) rather than a $ref to ValidationRuleKey’s own schema: that type lives in metadata-types, which does not derive JsonSchema yet (tracked by #812). ValidationRuleKey serializes transparently as its inner string (serde’s default newtype-struct behavior), so this is an accurate wire-shape description, not a placeholder.

string | null

scope

required

Anchoring category. Drives client-side rendering.

One of:

string

Attached to a specific request field. target is the field key.

string

Allowed value: field

string

Attached to the record being written or read. target is the id if known.

string

Allowed value: record

string

Attached to the request as a whole. target is always null.

string

Allowed value: global

target

Field key for field scope, record id for record scope, null otherwise. Always serialized, even when null.

string | null

Example

{
  "errors": [
    {
      "scope": "field"
    }
  ]
}