OffBlocks
  • πŸ‘‹Welcome to OffBlocks
  • Overview
    • πŸ’‘What we do
    • ✨Core Concepts
    • πŸ“œWhitepaper
    • ⛓️Supported Blockchains and Assets
    • ❔FAQ
  • Developer Guides
    • πŸ—οΈSystem Architecture
    • βš™οΈAPI Integration
      • πŸš€Getting Started
      • πŸ“―Postman
      • πŸ”‘Authentication
      • πŸ”Request Signatures
      • πŸ†”Idempotency
      • ⛓️Blockchain Identifiers
      • πŸ“’Blockchain Updates
      • πŸ“²Sign in With X
      • πŸ’°Fees
      • πŸ•ΉοΈSimulator
      • πŸ”’API Reference
        • πŸ¦Έβ€β™‚οΈCustomers
        • 🏦Accounts
        • πŸ’³Cards
        • πŸ”ƒTransactions
        • πŸͺWebhooks
        • πŸ•ΉοΈSimulator
        • πŸš‚Engine
      • ⏭️States and Transitions
        • πŸ¦Έβ€β™‚οΈCustomer States
        • 🏦Account States
        • πŸ’³Card States
        • πŸ”‘Authorisation States
        • πŸ”ƒTransaction States
    • 🧬Smart Contracts
      • OffBlocksEscrow.sol
      • OffBlocksSmartWalletFactory.sol
      • OffBlocksSmartWallet.sol
      • PendingWithdrawal.sol
      • Interfaces
    • πŸ”’Step-by-step Guide
      • 1️⃣API Credentials
      • 2️⃣Authentication
      • 3️⃣Request Preparation
      • 4️⃣Customer Creation
      • 5️⃣Customer Verification
      • 6️⃣Account Creation
      • 7️⃣Card Issuance
      • 8️⃣Card Authorisations
      • 9️⃣Webhooks
  • Use Cases
    • πŸ’°Wallet Providers
    • πŸ§‘β€πŸŒΎDeFi Apps
    • 🏦Neo-banks and FinTechs
Powered by GitBook
On this page
  1. Developer Guides
  2. API Integration

Request Signatures

PreviousAuthenticationNextIdempotency

Last updated 1 year ago

Signing Your Requests

For every authenticated request made to the OffBlocks API, it is essential to sign the request using an HTTP signature following a . Various open-source libraries are available to facilitate the generation of valid signatures. We are also actively working on publishing our own libraries to assist developers. For more information, please do not hesitate to contact us.

We actively develop a to support HTTP message signatures as well as contribute to a . Reach out to us if you're using other technologies on your backend and we'll be happy to assist with any issues integrating HTTP message signatures.

Supported Algorithms

While our API can theoretically accommodate multiple cryptographic algorithms for request signing, for the time being we only support as a signing algorithm.

Key Generation

In this guide we use openssl as a key generation tool. Feel free to use a tool of your choice, just make sure you generate keys using correct algorithm

Creating an ECDSA key pair for accessing our API is a straightforward process that involves just two commands:

  1. Create a private key.

    openssl ecparam -name secp384r1 -genkey -noout -out ec-secp384r1-priv-key.pem

    Sample contents of the ec-secp384r1-priv-key.pem private key in PEM format:

    -----BEGIN EC PRIVATE KEY-----
    MIGkAgEBBDB8VIl4tFsxpD/7QN7LNWqzWhBrksKY1gdbp6aFzN5kBM5+PtDL/C1Y
    nF+ACeMbf7ygBwYFK4EEACKhZANiAAQ1WCxX6Z7z/bbj6PntmWChGqtzfX5mmLLU
    +621jNM55fI2k5sPvPUmd891mU/L7FAPxowiE8Cu48hHXTayYqDaO9CE0m8eWWXg
    T6s+j8ku4qgs66a9GDh3IG3tjelZzVY=
    -----END EC PRIVATE KEY-----
  2. Create a public key by extracting it from the private key.

    openssl ec -in ec-secp384r1-priv-key.pem -pubout > ec-secp384r1-pub-key.pem

    Sample contents of the ec-secp384r1-pub-key.pem public key in PEM format:

    -----BEGIN PUBLIC KEY-----
    MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAENVgsV+me8/224+j57ZlgoRqrc31+Zpiy
    1PuttYzTOeXyNpObD7z1JnfPdZlPy+xQD8aMIhPAruPIR102smKg2jvQhNJvHlll
    4E+rPo/JLuKoLOumvRg4dyBt7Y3pWc1W
    -----END PUBLIC KEY-----

Registering your Public Key with the API

To enable our API to recognise your signatures, you need to upload the public key using the /auth/signing PUT endpoint. Please ensure that you set all the required environment variables (see Getting Started) in your Postman workspace before using this endpoint.

Make sure you encode your public key using base64 encoding before sending through our endpoint, otherwise the request will fail

Additionally, previously uploaded keys can be updated using the same endpoint or permanently removed using a DELETE request to /auth/signing.

Request Content Digest

While developers are also encouraged to use canonical JSON representation of request bodies to ensure stable hash calculation, we have made a decision to simply verify digest of byte array representation of the body as is. Please, make sure that request body is not transformed in any way after digest has been calculated or otherwise request verification may fail

While it is important to verify signature of the request itself, it is equally important to verify integrity of request body if it is provided. For this purpose we are using content digest header containing hash of request body calculated using pre-defined algorithm. The header is required for all API requests that are expected to have body, either POST or PUT. In line with , we are verifying Content-Digest header with request body hash calculated using sha-256 and/or sha-512 algorithms. It is also strongly advised to include Content-Digest header as part of signature verification in order to verify authenticity of the entire request.

βš™οΈ
πŸ”
pending IETF specification
Go library
Node.js library
ECDSA with curve P-384 DSS and SHA-384
HTTP Digest Header specification
  • Signing Your Requests
  • Supported Algorithms
  • Key Generation
  • Registering your Public Key with the API
  • PUTUpdate signing key
  • DELETEDelete signing key
  • Request Content Digest

Update signing key

put

Update public key used to sign API requests. When you upload your public key, a unique key ID is returned in response. This is different to your public key itself, and is required to sign your requests

Authorizations
Body
signingKeyIdstring Β· uuidRequired

Unique ID of your key. This is different to your public key itself, and is required to sign your requests

Example: 86b59965-6cf1-4633-9148-92848330fd1b
signingKeystring Β· byteRequired

Base64 encoded public key used for signing requests. Requirements for cryptographic algorithms and more details can be found in our documentation

Example: LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0=
Responses
204
Successful operation
400
Invalid request
401
Not authorised
500
Internal error
put
PUT /v1/auth/signing HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 303

{
  "signingKeyId": "86b59965-6cf1-4633-9148-92848330fd1b",
  "signingKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZZd0VBWUhLb1pJemowQ0FRWUZLNEVFQUFvRFFnQUUzTEw1RldmVFgvL3BJaXNEL0xneFVIT2lxdlFTSUVWTgpGekloOTdLZXBlWk1iZVZsUGd1akZ4Yk5MN2x1ZVhRQnBpUWUzNmZLN0xSbXZNNHdEaWZFTkE9PQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0="
}

No content

Delete signing key

delete

Delete public key used to sign API requests

Authorizations
Body
signingKeyIdstring Β· uuidRequired

Unique ID of your key. This is different to your public key itself, and is required to sign your requests

Example: 86b59965-6cf1-4633-9148-92848330fd1b
Responses
204
Successful operation
400
Invalid request
401
Not authorised
500
Internal error
delete
DELETE /v1/auth/signing HTTP/1.1
Host: api.offblocks.xyz
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 55

{
  "signingKeyId": "86b59965-6cf1-4633-9148-92848330fd1b"
}

No content