Rhythm API: Troubleshooting 401 Unauthorized Errors

This document explains the most common causes of 401 Unauthorized responses when calling the Rhythm APIs and how to resolve them.

1. Confirm the Authorization header

All Rhythm APIs require a valid OAuth 2.0 access token sent using the Bearer scheme:

Authorization: Bearer <access_token>

Ensure:

• The header name is exactly Authorization
• The value starts with Bearer (including the space)
• The token has not expired

2. Verify the OAuth audience configuration

A frequent cause of 401 errors is an incorrect OAuth audience value when requesting the access token.

For Client Credentials and most server-to-server flows, the audience must be:

https://api.rhythmsoftware.com

If the audience does not match what the API expects, the token will be rejected even if it is otherwise valid.

3. Decode the access token and validate required claims

Decode the JWT access token and confirm the following claims are present:

• http://rhythmsoftware.com/tenant_id
• http://rhythmsoftware.com/contact_id

Optional but commonly present:

• http://rhythmsoftware.com/customer_id

The contact_id claim is required for most Rolodex and Membership API calls and must be used in request paths where a contact identifier is required.

4. First-time login edge case

If the user represented by the token has never logged into the Rhythm application, the contact_id claim may not yet exist. In this case:

• The token may be valid
• API calls that require a contact context will still return 401 Unauthorized

Have the user log into the Rhythm UI at least once to ensure the contact record is created.

5. Validate the contact using the Rolodex API

You can confirm that the token resolves to a valid contact by calling the Rolodex endpoint:

GET https://api.rhythmsoftware.com/rolodex-v1/contacts/current

If this call succeeds, the token is valid and the contact is correctly associated.

6. Confirm the correct API base URL

Different Rhythm services use different base URLs. Common examples:

• Rolodex API:

  https://api.rhythmsoftware.com/rolodex-v1

• Membership API:

  https://api.rhythmsoftware.com/membership-v1

Using the wrong service base URL with an otherwise valid token will result in a 401 response.

7. Summary checklist

If you receive a 401 Unauthorized error, verify:

• The Authorization: Bearer header is present and correct
• The token has not expired
• The OAuth audience is https://api.rhythmsoftware.com
• The token contains tenant_id and contact_id claims
• The user has logged into the Rhythm UI at least once
• The request is sent to the correct service base URL