ReferenceAPI ReferenceSigner

Create signer factor

POST/signers/{signer}/factors●Add a new authentication factor to a signer.

Supported factor types include key-pair for cryptographic key authentication and oauth-client-credentials for OAuth 2.0 token exchange. Each factor stores the credentials needed to verify the signer's identity.

Secrets such as private keys and client secrets are encrypted at rest and never returned in API responses.

Broadcasts the signer-factor-created signal. Use effects to subscribe.

POST
/signers/{signer}/factors

Usage Examples

curl -X POST "http://localhost:3000/v2/signers/string/factors" \  -H "x-ledger: <YOUR LEDGER HANDLE>" \  -H "Content-Type: application/json" \  -d '{    "hash": "82baa21c2f24351786a768bb66bf258cbbee9092f53549810ac2e9fdec809036",    "data": {      "handle": "signing-key",      "signer": "tesla-bank-admin",      "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",      "format": "ed25519-raw",      "schema": "key-pair",      "custom": {        "title": "Admin backup signing key"      }    },    "meta": {      "proofs": [        {          "method": "ed25519-v2",          "digest": "bcbc413a6415be50a9551e3c76f5c32bb00d20025cf5a3c1176ba04752484ddc",          "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",          "result": "JonHuzyJ1iX1Kr9BYd3BxjZPJkZurFki/3XzMdgSU1HZk72LKYH5Jxoml+q7FytzCQ7h6z1Mg8Ghn9UVEUksDA==",          "custom": {            "moment": "2025-04-05T14:30:00.000Z",            "status": "created"          }        }      ]    }  }'
{
  "luid": "$snf.-01xK1rTtU2dS4wX3",
  "hash": "82baa21c2f24351786a768bb66bf258cbbee9092f53549810ac2e9fdec809036",
  "data": {
    "handle": "signing-key",
    "signer": "tesla-bank-admin",
    "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",
    "format": "ed25519-raw",
    "schema": "key-pair",
    "custom": {
      "title": "Admin backup signing key"
    }
  },
  "meta": {
    "status": "created",
    "moment": "2025-04-05T14:30:00.050Z",
    "owners": [
      "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk="
    ],
    "proofs": [
      {
        "signer": "tesla-bank-admin",
        "method": "ed25519-v2",
        "digest": "bcbc413a6415be50a9551e3c76f5c32bb00d20025cf5a3c1176ba04752484ddc",
        "public": "dsZvr0rEw9sIffHlv1VP65x1NB8GeXezIv6HONk1SIk=",
        "result": "JonHuzyJ1iX1Kr9BYd3BxjZPJkZurFki/3XzMdgSU1HZk72LKYH5Jxoml+q7FytzCQ7h6z1Mg8Ghn9UVEUksDA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z",
          "status": "created"
        }
      },
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "a24ccbca89db875fe98ce4d1b3f0b9b286e7891cc8e1377b0252be3420e8423a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "0g5td5sn76a0LKm6rywjdmj8oldC42AqvvMMS90x4UEPln2BcNVx//9oyM0kwEpUs9hkxoibuVHDxX618577Bw==",
        "custom": {
          "luid": "$snf.-01xK1rTtU2dS4wX3",
          "moment": "2025-04-05T14:30:00.050Z",
          "status": "created"
        }
      }
    ]
  }
}
{
  "hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
  "data": {
    "reason": "auth.unauthorized",
    "detail": "Invalid token."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
  "data": {
    "reason": "auth.forbidden",
    "detail": "Request is not authorized"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}
{
  "hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
  "data": {
    "reason": "record.duplicated",
    "detail": "Ledger with handle instant-payments already exists."
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
  "data": {
    "custom": {
      "errors": [
        {
          "instancePath": "/handle",
          "schemaPath": "#/properties/handle/pattern",
          "keyword": "pattern",
          "params": {
            "pattern": "^[a-zA-Z0-9_\\-+.]+$"
          },
          "message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
        }
      ]
    },
    "reason": "record.schema-invalid",
    "detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

{
  "hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
  "data": {
    "reason": "api.unexpected-error",
    "detail": "An unexpected error occurred"
  },
  "meta": {
    "proofs": [
      {
        "signer": "system",
        "method": "ed25519-v2",
        "digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
        "public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
        "result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
        "custom": {
          "moment": "2025-04-05T14:30:00.000Z"
        }
      }
    ]
  }
}

Path Parameters

signer*|

The unique identifier of the signer this factor belongs to it is luid or handle (address).

Query Parameters

include?array<>

The references to include with the signer factor.

Header Parameters

x-ledger?|

The unique identifier of ledger in context for multi tenant requests.

Request Body

application/json

Signer factor body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

Add signer proof POST

Appends a signed proof to the record. The proof must be signed against the record's current hash. Use proofs to change status, update labels, or record custom data — see [About Proofs](/ledger/structuring-data/about-proofs) for details. Returns the updated record with the new proof in `meta.proofs`. Broadcasts the `signer-proofs-added` signal. Use [effects](/ledger/reference/api/effect) to subscribe.

List signer factors GET

Use this endpoint to review the authentication factors configured for a signer, such as key pairs or OAuth credentials. Supported filters: - `data.public` — public key - `data.schema` — factor schema - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — domain scope - `data.custom.<field>` — any custom field (may be slower on large datasets)