Migrating to API Key Signatures

Overview

Devengo has transitioned to a signature-based authentication model. Instead of obtaining a short-lived JWT token via a dedicated endpoint and including it in subsequent requests, your integration now generates a cryptographic signature for each request using a long-lived secret key associated with your API Key.

What changes in your integration

With JWT Token authentication, every session required a dedicated round-trip to the /tokens endpoint to exchange your client credentials for a short-lived token. That token was then attached to subsequent requests until it expired, at which point your integration had to obtain a new one. This meant maintaining token renewal logic, handling expiry edge cases, and making an extra network request before any real work could happen.

With API Key Signatures, there is no token endpoint and no concept of expiry. Each request is self-authenticated: your client computes a signature on the fly and sends it alongside the request. Devengo verifies it independently, without any prior exchange.

sequenceDiagram
    participant App as Your application
    participant API as Devengo API
 
    Note over App: Generate nonce + timestamp<br/>Compute signature
    App->>API: GET /accounts<br/>X-Devengo-Api-Key-Id, Nonce, Timestamp, Signature
    API-->>App: 200 OK
 
    Note over App: Generate new nonce + timestamp<br/>Compute signature
    App->>API: POST /payments<br/>X-Devengo-Api-Key-Id, Nonce, Timestamp, Signature
    API-->>App: 200 OK
 
    Note over App,API: No token endpoint. No expiry.<br/>Each request is self-authenticated.

Each request is self-authenticated. There is no separate token endpoint call, no token expiry to manage, and no renewal logic to maintain.

For the full technical specification, see the Authentication reference.

Migration steps

Step 1 — Create an API Key in the Control Panel

When creating the key, select API version 202512. This version is fully compatible with the signature scheme and avoids having to apply additional changes introduced in later versions.

Important: Copy and store the secret key immediately after creation — it will not be shown again. Treat it like a private key: store it in a secrets manager or environment variable, never in source code or version control.

Step 2 — Implement a signature-capable client

Implement a new client alongside your existing one. Do not replace the existing integration yet — you will run both in parallel during the rollout. Here you have a guide about how to implement it.

Verify your implementation

Use the dedicated test endpoints to confirm your signature logic is correct before integrating with real resources:

A successful response from these endpoints confirms your client is ready.

Step 3 — Use a feature flag to switch between clients

Keep both client implementations active and control which one is used via a feature flag. This ensures you can revert instantly if any issue is detected, without requiring a deployment.

// This is an example on how you could keep both client versions with a Featura Flag system.
function getDevengoClient() {
  if (featureFlags.isEnabled("devengo_api_signature_auth")) {
    return new DevengoClientWithApiSignature({
      apiKeyId: "apk_XXX",
      apiKeySecret: "xyz..."
    });
  }

  return new DevengoClientWithToken();
}

🚧
When using the new client version, do not call the endpoint to get a new Token.

Do not hardcode the switch or delete the old client at this stage.

Step 4 — Validate in Sandbox

Before deploying to production, enable the new client against the Sandbox environment and run your full test suite. Be aware that Sabdbox and Production do not share API Keys, you must create an API Key per environment.

Key things to verify:

Authentication succeeds for all request types (GET, POST, PATCH, DELETE).
Requests with a body pass the correct Base64-encoded body as part of the signed payload.
Requests without a body omit the body component from the signed payload entirely.
A fresh UUID nonce is generated for every request.

Refer to Sandbox limitations and test data for details specific to the Sandbox environment.

Step 5 — Gradual production rollout

Once the new client is validated in Sandbox, deploy it to production with the feature flag disabled. Then enable it progressively:

Enable for a small percentage of traffic (e.g. 5–10%).
Monitor your observability dashboards for authentication errors (401, 403) and latency regressions.
Once metrics look healthy after a reasonable observation window, expand the rollout to additional traffic or services.
When you have full confidence, enable the flag globally across all services.

If any issue appears during the rollout, disable the flag to revert to the JWT Token client immediately — no deployment required.

Step 6 — Remove the legacy integration

Once the new client is stable across all traffic and services, clean up your codebase:

Delete the legacy client implementation and any associated token renewal or caching logic.
Remove the feature flag and any branching logic that references it.
Remove the environment variables for JWT Token credentials.

Troubleshooting

401 — api_key_signature_invalid The signature did not match. Verify that: (1) the payload components are concatenated in the correct order — Base64(body) + nonce + timestamp + api_key_id; (2) the body is Base64-encoded before concatenation; (3) the body used for signing is byte-for-byte identical to the body sent in the request; (4) requests without a body omit the body component entirely.

403 Forbidden API Keys can be scoped to specific operations. Review the permissions assigned to your key in the Control Panel and ensure the required scopes are enabled.

Requests succeed in Sandbox but fail in production Verify that your production environment variables reference a production API Key, not the Sandbox one. Keys are environment-specific and cannot be used across environments.

Support

If you encounter any issues during the migration that are not covered above, open a ticket from the Control Panel. Include your API Key ID (never the secret) and a description of the failing request to expedite the diagnosis.