Pinal Developers

API reference

Passwords

Zero-knowledge vault access. Items are encrypted on the person's devices.

Base URL https://api.pinal.tech/v1

Request a fill

POST /passwords/autofill

Asks the person's device to fill a login for origin. They approve it there; you get back an encrypted item only your app's session key can open.

Request body application/json

  • origin string required
  • public_key string required

    Your ephemeral X25519 public key (base64url).

Responses

curl -X POST "https://api.pinal.tech/v1/passwords/autofill" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "https://example.com",
    "public_key": "string"
  }'
Response · 202
{
  "request_id": "string",
  "expires_at": "2026-11-19T15:20:04Z"
}

List vault items

GET /passwords/items

Encrypted items. Decrypting needs the person's vault key, which never leaves their devices.

Query parameters

  • limit integer

    Items per page, 1–100.

  • cursor string

    Opaque cursor from a previous page's next_cursor.

Responses

curl "https://api.pinal.tech/v1/passwords/items" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response · 200
{
  "items": [
    {
      "id": "string",
      "kind": "login",
      "origins": [
        "string"
      ],
      "ciphertext": "string",
      "updated_at": "2026-11-19T15:20:04Z"
    }
  ],
  "next_cursor": "string"
}

Save an item

POST /passwords/items

Stores an item you encrypted client-side with the person's vault key.

Request body application/json

  • id string read-only
  • kind string

    One of login card note identity

  • origins array of string
  • ciphertext string

    XChaCha20-Poly1305, base64url. Pinal can't read it.

  • updated_at string (date-time) read-only

Responses

curl -X POST "https://api.pinal.tech/v1/passwords/items" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "string",
    "kind": "login",
    "origins": [
      "string"
    ],
    "ciphertext": "string",
    "updated_at": "2026-11-19T15:20:04Z"
  }'
Response · 201
{
  "id": "string",
  "kind": "login",
  "origins": [
    "string"
  ],
  "ciphertext": "string",
  "updated_at": "2026-11-19T15:20:04Z"
}