> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvera.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve Nuvera partner API authentication, signing, permission, and rotation failures

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

## Authentication failures

<AccordionGroup>
  <Accordion title="Missing API key">
    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.
  </Accordion>

  <Accordion title="Invalid API key">
    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.
  </Accordion>

  <Accordion title="Revoked key">
    A revoked key cannot be used again. Deploy an active replacement key and update any stale service configuration.
  </Accordion>

  <Accordion title="Disabled application">
    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.
  </Accordion>
</AccordionGroup>

## Signed JWT failures

<AccordionGroup>
  <Accordion title="Expired JWT">
    Generate a new JWT for every request. The token lifetime must be 60 seconds or less, and `exp` must be close to `iat`.
  </Accordion>

  <Accordion title="Method mismatch">The JWT `method` claim must match the HTTP method. `POST` and `GET` are different signatures.</Accordion>

  <Accordion title="URI mismatch">
    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.
  </Accordion>

  <Accordion title="Body hash mismatch">
    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.
  </Accordion>

  <Accordion title="Replay detected">
    Use a unique `jti` for every request. Reusing a token or nonce inside the token lifetime is rejected.
  </Accordion>

  <Accordion title="Wrong issuer or audience">
    Use `iss=nuvera-api` and `aud=nuvera-rest-api`.
  </Accordion>
</AccordionGroup>

## 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.