Guides
Start typing to search…

Create credential

Overview

This guide explains how to add a credential within a Due Vault scope, which will be further used for all signing operations.

Prerequisites

  • OpenSSL toolkit installed (or any other key management tool you're comfortable with)
  • API access token
  • Basic understanding of EVM wallets and cryptographic signing

Supported algorithms:

  • Elliptic Curve (secp256r1, ...)

Step 1: Generate Key Pair

If you don't have a key pair, create one using OpenSSL:

# Generate a new private key and save it to private.pem file
openssl ecparam -genkey -name prime256v1 -out private.pem

# Derive a public key from the private key and save to public.pem file
openssl ec -in private.pem -pubout -out public.pem

Tip: To get your public key as a single-line string for easier use in JSON:

cat public.pem | jq -Rs .

Keep your private key secure - it will be used for all signing operations.

Step 2: Add Credentials

Credentials are used for signing operations in the vault system. Let's add your first credential. See Credentials API Reference for more details.

Initialize Credential Creation

Note: This process uses Pattern 1: Direct JSON Signing - you'll construct and sign a JSON object directly.

Send an initialization request to start the credential creation process:

curl --location 'https://api.due.network/v1/vaults/credentials/init' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "kind": "Key",
    "name": "Primary key"
}'

Response:

{
    "challenge": "CONnem_8mBAOUeLPL55EQBKV9EfxpIaFHIqtl6b7nmw",
    "clientDataHash": "cff7a7e1bfd1b99996f40046db72a1d1dcd847d6b6c3df22e9ff4407a7e73a9d",
    "kind": "Key"
}

Prepare and Sign the Challenge

You need to create a JSON object containing the clientDataHash from the response and your public key in PEM format.

Important: To avoid issues with escape sequences and special characters, create the JSON data in a file:

# Create JSON file with clientDataHash and public key
cat > challenge.json << EOF
{"clientDataHash":"<clientDataHash_from_response>","publicKey":$(cat public.pem | jq -Rs .)}
EOF

For example, your challenge.json file should look like:

{"clientDataHash":"cff7a7e1bfd1b99996f40046db72a1d1dcd847d6b6c3df22e9ff4407a7e73a9d","publicKey":"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAERorJRL7hy7WQUQEcIHtcWeZVvwxf\nZlviYrhHHHogLJ7dNc94ObdRG9++bC+WfWsGlb24XhiDZGcBylSAmGps+g==\n-----END PUBLIC KEY-----\n"}

To sign this JSON, use the following command:

# Sign the JSON data from file (removing any trailing newline before signing)
cat challenge.json | tr -d '\n' | openssl dgst -sha256 -sign private.pem | xxd -p | tr -d '\n'

Command breakdown:

  • cat challenge.json - Read the JSON file
  • tr -d '\n' - Remove any trailing newline from the file
  • openssl dgst -sha256 -sign private.pem - Create SHA256 hash and sign with your private key
  • xxd -p - Convert binary signature to hexadecimal
  • tr -d '\n' - Remove newlines from hex output for a clean string

Result: A hex-encoded signature like:

30450220129dd58d6492fc5b505d46a82887c708ba73cc189f1d868f6508ba8b093cdc20022100f7217bcb5d83da3ed1ee1231dd8edd852133b14fb54e0032baf463a1b64a0d04

Finalize Credential Creation

Submit the signed challenge:

curl --location 'https://api.due.network/v1/vaults/credentials' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "kind": "Key",
    "signature": "30450220129dd58d6492fc5b505d46a82887c708ba73cc189f1d868f6508ba8b093cdc20022100f7217bcb5d83da3ed1ee1231dd8edd852133b14fb54e0032baf463a1b64a0d04",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAERorJRL7hy7WQUQEcIHtcWeZVvwxf\nZlviYrhHHHogLJ7dNc94ObdRG9++bC+WfWsGlb24XhiDZGcBylSAmGps+g==\n-----END PUBLIC KEY-----\n",
    "challenge": "CONnem_8mBAOUeLPL55EQBKV9EfxpIaFHIqtl6b7nmw"
}'

Response:

{
    "id": "passkey_xonETR6gAv3wIyhy8ehjx",
    "kind": "Key",
    "algorithm": "ECDSA:256:P-256",
    "location": {
        "deviceType": "",
        "deviceOS": ""
    },
    "name": "Primary key",
    "publicKey": "...",
    "hasWalletAccess": true,
    "createdAt": "2025-09-09T17:09:28.313965114Z",
    "approveUntil": null,
    "isActive": true
}

Important Notes:

  • The first credential is automatically approved and ready to use ("approveUntil": null)
  • Additional credentials are created with "isActive": true but require approval if "approveUntil" is set (see Additional Credentials guide)
  • The "approveUntil" field indicates if approval is needed:
    • null = fully approved and ready to use
    • timestamp = requires approval before this deadline
  • Save the credential ID (passkey_xonETR6gAv3wIyhy8ehjx) - you'll need it for signing operations

You can always retrieve this ID later by making a request to the credentials endpoint.

Next Steps


Updated about 1 month ago