Skip to main content
Most REST API failures come from one of four areas: API key state, JWT signature claims, permissions, or request body hash.

​
Authentication failures

Include the one-time secret API key in x-api-key. The value must be the full key, not the prefix or last four characters shown in the UI.
Verify that the service is using the key from the partner secret manager. Nuvera cannot redisplay old raw keys. If the key was lost, create a replacement key and revoke the lost key.
A revoked key cannot be used again. Deploy an active replacement key and update any stale service configuration.
A disabled API application rejects requests even when the key and JWT are valid. Re-enable it only after the support or security issue is resolved.

​
Signed JWT failures

Generate a new JWT for every request. The token lifetime must be 60 seconds or less, and exp must be close to iat.
The JWT method claim must match the HTTP method. POST and GET are different signatures.
The JWT uri claim must contain the exact path and query string sent to Nuvera. Do not include the protocol or host. Query parameter order must match the actual request.
Hash the exact request body bytes. For no-body requests, hash an empty byte string. For JSON, send exactly the same serialized string that was signed.
Use a unique jti for every request. Reusing a token or nonce inside the token lifetime is rejected.
Use iss=nuvera-api and aud=nuvera-rest-api.

​
Permission failures

Each REST route requires an explicit permission. If a request returns a permission error:
  1. Open the API application.
  2. Confirm the route area has the required permission.
  3. Add the matching read permission when granting a write permission.
  4. Save and retry with a newly signed request.
Admins can adjust permissions from the organization hub for partner support, but partners should keep least-privilege ownership of normal permission changes.

​
Multipart hash failures

Multipart uploads are validated after fields and files are parsed. If a multipart request fails:
  • Confirm the JWT bodyHash was calculated from the canonical multipart object, not the raw boundary stream.
  • Confirm every form field value is included as a string.
  • Confirm repeated field values are sorted.
  • Confirm file fieldName, fileName, mimeType, size, and file SHA-256 are included.
  • Confirm files are sorted by field name, file name, size, and SHA-256 before hashing.
Proof artifacts should include form fields, file name, MIME type, size, and file SHA-256, never raw file bytes.

​
Support escalation checklist

When escalating to Nuvera support, provide:
  • API application name and key last four characters.
  • Timestamp and request path.
  • HTTP status and response body.
  • Redacted request headers.
  • Request body hash and JWT claims after redacting the API key and token signature.
Do not send raw API keys, JWTs, private keys, or file bytes.