For agents (internet-banking account API)

Read this page before generating a client. The human guide starts at overview. Contract: /openapi/ib.yaml (OpenAPI 3.1, only the operations this credential can call; every operation also carries x-audience). Machine indexes: /llms.txt and /.well-known/api-catalog. Do not invent paths.

Facts

Signing algorithm, canonical string, Node sign(), and an offline test vector: request-signing.

End-to-end flow

1. Token

POST https://auth.api.corpx.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}

{ "access_token": "eyJ…", "expires_in": 300, "token_type": "Bearer" }

2. Build the canonical string (LF, not CRLF):

METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_OR_EMPTY\nSHA256_HEX

Empty body SHA-256 is always e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. Sign as detached JWS (<protected>..<signature>), ES256 = 64-byte R||S (not DER). Put kid in the protected header.

3. Self-test (creates nothing; valid: false is still HTTP 200):

POST https://client.api.corpx.com/v1/security/signature/verify
Authorization: Bearer {access_token}
X-Tenant-Id: {tenantId}
X-Request-Timestamp: {unixSeconds}
X-Content-SHA256: {sha256(jsonBody)}
X-Request-Signature: {jws}
Content-Type: application/json
{
  "method": "POST",
  "path": "/v1/accounts/acc-123/pix/payments",
  "timestamp": "1789412400",
  "idempotencyKey": "4f1e3b7a-9d2c-4a11-8f55-2b0c6a7d1e90",
  "body": "{\"amount\":1000}",
  "signature": "{jws}"
}

Compare canonicalString character-by-character when valid is false.

4. Balance

GET https://client.api.corpx.com/v1/accounts/{accountId}/balance
Authorization: Bearer {access_token}
X-Tenant-Id: {tenantId}
X-Request-Timestamp: {unixSeconds}
X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
X-Request-Signature: {jws}

{
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "total": 18254.17,
  "locked": 500.00,
  "available": 17754.17,
  "currency": "BRL",
  "updatedAt": "2026-02-05T22:00:00Z"
}

5. PIX out (only after verify + balance succeed)

POST https://client.api.corpx.com/v1/accounts/{accountId}/pix/out
Authorization: Bearer {access_token}
X-Tenant-Id: {tenantId}
Idempotency-Key: {uuid}
X-Request-Timestamp: {unixSeconds}
X-Content-SHA256: {sha256(jsonBody)}
X-Request-Signature: {jws}
Content-Type: application/json
{
  "amount": 100.00,
  "keyType": "CPF",
  "key": "12345678901",
  "description": "order-12345",
  "identifier": "order-12345"
}

Treat 200 COMPLETED as done. 202 / 207 are indeterminate — wait for pix.out.completed / failed / timeout or look up the payment. 422 is a business rejection (errorCode).

6. Webhook (create once, with accountId):

{
  "url": "https://example.com/webhooks/account",
  "accountId": "{accountId}",
  "authType": "HMAC",
  "secret": "{webhookSecret}",
  "eventTypes": ["pix.in.completed", "pix.out.completed", "pix.out.failed", "qrcode.paid"]
}

Verify X-Signature = base64(HMAC_SHA256(secret, raw_body)) on the raw bytes. Reply 2xx quickly.

Offline test vector

Public key, canonical string, content SHA-256 and a valid JWS are in request-signing § test vector. kid = cfe8291443215153e11b76a7a533dd3c. Use it to unit-test your signer before calling the API.

Error decision table

Human-facing detail: errors.