When JWT authentication fails, the API returns a generic 401 Authentication required error. For security reasons, the API response does not include specific failure details for any authentication method. However, these failures are logged on the server side with complete diagnostic information.

If you are unable to resolve authentication failures using the troubleshooting steps below, contact [email protected] for assistance.

Possible points of failure

JWT authentication can fail at various validation points. Review the following checklist to identify and resolve common issues:

1. Authorization header format

   Verify that the generated JWT token is passed in the request header Authorization as Bearer token:

   Authorization: Bearer <your_jwt_token>

   Ensure there is a space between "Bearer" and the token value.

2. JWT is for SnapLogic public APIs

   The JWT-based authentication is specifically for SnapLogic public APIs. Ensure you are calling a public API endpoint, not a UI or other internal endpoint.

3. Required claims present

   Check the JWT payload and ensure these claims are present:

   • iat: Issued-at time (required)
   • exp: Expiration time (required)
   • iss: Issuer ID (required)
   • sub or snaplogic_username: Username (required; use snaplogic_username if sub cannot be modified, depending on the IdP)
   • aud or snaplogic_aud: Audience (required; use snaplogic_aud if aud cannot be modified, depending on the IdP)
   • org or snaplogic_org: Organization name (required; use snaplogic_org if there is a conflict with org)
4. Organization claim matches environment

   Check the custom claim org or snaplogic_org (if there is a conflict with org) and ensure its value matches the customer environment on SnapLogic where JWT is configured.

   The organization name is case-sensitive and must match exactly.

5. Username claim matches SnapLogic user

   Check the sub claim. It should indicate the username in SnapLogic if it is configurable (depends on the IdP). Otherwise, this information must be provided in the custom claim snaplogic_username.

   Verify that:

   • The username exists in SnapLogic
   • The username is active and not disabled
   • The username is spelled correctly (usernames are case-sensitive)
6. Environment configured for JWT

   Verify that the environment specified in the org or snaplogic_org claim is configured for JWT-based authentication in Admin Manager.

   To check:

   1. Log in to SnapLogic Admin Manager
   2. Navigate to Authentication > JWT
   3. Verify that the Issuer ID and JWKS endpoint are configured

   Refer to JWT configuration for configuration details.

7. Issuer ID matches

   In the JWT-based authentication settings in Admin Manager (see point 6 above), verify the Issuer ID matches the value for the iss claim in the JWT.

   The issuer ID must match exactly, including protocol (http/https), domain, and path.

8. JWKS endpoint is valid and accessible

   In the JWT-based authentication settings in Admin Manager (see point 6 above), verify the JWKS endpoint. Calling it must return at least one public key to verify the JWT signature.

   If the JWT payload includes a kid (Key ID) in the header, a key matching that kid must be present in the JWKS response.

   To test the JWKS endpoint:

   curl https://your-idp.com/.well-known/jwks.json

   The response should be a JSON object containing an array of keys.

9. Audience claim matches SnapLogic API URL

   Check the aud claim or custom snaplogic_aud claim (if aud is not configurable, depending on the IdP). It must point to SnapLogic:

   https://elastic.snaplogic.com/api/1/rest/public

   Note: The URL varies by POD (US, EMEA, UAT, etc.). Ensure you are using the correct URL for your SnapLogic instance.

10. Signing algorithm is RS256 or ES256

    Ensure that RS256 or ES256 (asymmetric and secure algorithms) were used for signing the JWT.

    SnapLogic does not accept JWTs signed with symmetric algorithms like HS256 for security reasons.

    You can check the signing algorithm in the JWT header by decoding the token.

11. JWT has not expired

    Check the exp claim. The JWT cannot have expired.

    The exp value is a Unix timestamp (seconds since January 1, 1970 UTC). Verify that:

    • The expiration time is in the future
    • Your system clock is accurate
    • You account for timezone differences when generating tokens
12. JWT not issued in the future

    Check the iat claim, which cannot be issued in the future.

    The iat value is a Unix timestamp (seconds since January 1, 1970 UTC). Verify that:

    • The issued-at time is in the past
    • Your system clock is accurate
    • You account for timezone differences when generating tokens

Common error scenarios