Secrets API reference

Project-scoped write-only runtime secrets.

Published contracts: @socra/secret-api@0.0.1.

Authenticated request and response

Replace the example Project identifier with your own authorized Project. IAM permissions and Secret service enablement on that Project apply. List and get return metadata. Secret values are write-only and are never included in responses; do not put live secret values into transcripts.

This illustrative read uses an existing access token. Set ACCESS_TOKEN through your authorized credential provider; keep it out of source, logs and shared shell history. The identifiers and response below are fictional, validated against the published package. They are not a runtime execution receipt.

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Accept: application/json' \
  'https://secret.socra.cloud/v1/secrets?project_id=proj_01m00000000000000000000000&limit=1'

Example successful response body:

{
  "data": [
    {
      "id": "sec_01m00000000000000000000000",
      "project_id": "proj_01m00000000000000000000000",
      "name": "example-secret",
      "description": null,
      "status": "active",
      "latest_version": null,
      "created_at": "2026-10-20T12:00:00.000Z",
      "updated_at": "2026-10-20T12:00:00.000Z"
    }
  ],
  "has_more": false
}

For body requests, send JSON with Content-Type: application/json and the exact body fields listed under the operation. Required scopes, when declared, appear with the operation. A token and a valid request shape do not replace the service's authorization rules.

Handle unsuccessful responses

Inspect the HTTP status and response body before taking another action. The published API client retains status, method, URL and body on APIError. It accepts a JSON error object with optional error, message, code and details fields; it also preserves a text or empty body. The method contracts below do not declare a complete per-operation error catalog.

An illustrative JSON error body (field names follow the client contract; the message is an example):

{
  "message": "The request was rejected. Check the status and service permissions."
}

• For 400 or another validation response, compare the named field, required fields, types, bounds and accepted values with this reference before correcting the request.
• For 401, obtain or refresh your token through the supported authorization path. Never paste a token into a bug report.
• For 403, stop and ask the resource owner to verify the intended principal, Account or Project, required permission and service enablement. An access denial is not evidence of a runtime defect.
• For 404, verify the exact resource identifier and Account or Project context with its owner; do not recreate a resource merely because a read failed.
• For 429, follow Retry-After if the service supplies it. These contracts specify no universal rate limit or retry interval.
• For a 5xx response or interrupted connection after a write, inspect supported resource state before retrying. The effect may be uncertain; automatic replay can duplicate work.

These are status-based troubleshooting steps, not a promise that each operation returns each status or the sample body. Preserve the exact status and redacted body when requesting help.