Create a request

POST /v1/requests

Requires the requests:write scope and an Idempotency-Key header. Returns a short_code from which you assemble the collect link.

Request

curl -X POST https://api.credenshare.io/v1/requests \
  -H "Authorization: Bearer crs_sk_live_<keyId>.<authSecret>" \
  -H "Idempotency-Key: onboard-acme-2026-09-03" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Production database password",
        "description": "We need the read-only credential for the reporting job.",
        "public_key": "<base64url P-256 public key>",
        "fields": [
          { "item": "Username", "type": "text" },
          { "item": "Password", "type": "password" }
        ],
        "expired_at": "2026-09-30T12:00:00Z",
        "max_submission": 1
      }'

Body

There is no created_by and no id. The acting key decides the owner; you do not get to name it.

fields

fields is required and must contain at least one entry. Each entry is:

expired_at defaults to 30 days

Omit expired_at and the request expires 30 days from creation, matching what the app has always defaulted to.

This is a real default, not a formality. A request stored with no expiry is invisible: the list query is expired_at > current_timestamp, and NULL satisfies neither that nor its negation, so such a request is neither active nor expired. It would be created successfully, readable by short code, and absent from both the API list and the owner's own dashboard. The alternative — a collect link that stays open forever — is not a sensible thing to get by leaving a field out either.

organization_id

Send it only if it matches the organization your key already acts for, or omit it and let the key decide. A mismatch is refused:

{
  "success": false,
  "message": "organization_id does not match the organization this key acts for. Omit it — the key determines the organization — or mint a key bound to that organization.",
  "error_code": 78
}

Taking this field from the body unchecked was an authorization bypass on the shares surface once. It is validated here for the same reason.

Idempotency

The Idempotency-Key header is required, and more consequentially here than on shares: a duplicated request is not inert, because a human can fill it in. Two collect links in the world when you believe you created one means the same credential can be handed over twice.

The semantics are identical to share creates — the raw request body is hashed byte for byte, keys are scoped to the API key that used them and retained for 24 hours:

A replay returns 200, not 201. Treat both as success.

Success response

201 Created:

{
  "short_code": "a1b2c3d4",
  "expired_at": "2026-09-30T12:00:00Z",
  "public_key": "<the key you sent>"
}

There is no url field, for the same reason share creates have none: only you know which origin your recipients use. Assemble it yourself:

https://crs.sh/r/a1b2c3d4

That link carries no key material and is safe to send over ordinary channels. public_key comes back so you can confirm what was stored is the key you generated.

Errors

403 with code 78 is ambiguous by design — the generic message covers both a missing scope and an organization mismatch. The message field tells the two apart; the code does not.

Next

Give the person the collect link, then read the submissions once they have filled it in. Subscribe to request.submitted if you would rather be told than poll — see Webhook events.