An API key lets a system outside Rhythm act for your organization through Rhythm’s API without anyone signing in. That system might be a partner integration, an association-management add-on, or a web application that signs in your members. Because the key acts for your organization, treat it like a password: anyone who has it can read and change your data through the API while the key is valid.
Two Kinds of Key
When you create a key, you choose one of two kinds:
- A non-interactive key, also called a machine-to-machine or computer-to-computer key, is for back-end integrations and server-to-server code. This is the most common kind. All three terms mean the same thing: a credential used by software, not by a person signing in.
- A web SSO key is for a web application that signs in your members through single sign-on. A web SSO key also needs the addresses where the identity provider can send people after sign-in and sign them out.
A web SSO key supports the OpenID Connect and Authorization Code flows. Sign-in has to start in a browser: the application sends the person to the identity provider's authorize address, the person signs in there, and the identity provider sends them back to one of the key's registered callback addresses with a code. The application then exchanges that code for a token. Sign-in cannot be completed entirely through a back-end tool without a browser step, and the request fails if the redirect address is not registered on the key. If your application reports a sign-in error because it did not receive a username, confirm that the identity provider is sending a claim mapped to Rhythm's username field. NameID is the usual choice, and email is a common fallback when NameID cannot be sent. If an integration is missing an expected profile field, check whether your code should read it from the ID token's claims or call a separate profile endpoint with the access token, because those two places do not always include the same fields.
Tip
Every account's bundled setup includes a limited number of registered applications, which are API keys. If an integration project needs more than that, you need a separately contracted identity-provider account instead of adding more keys to the bundled plan. Contact Rhythm to discuss your options before you commit to an integration that depends on exceeding the limit.
Choose the key based on what the integration does. A server process that only reads or writes API data, with no person present, should use a non-interactive key and the machine-to-machine client credentials flow described below. A web application where a member signs in with their Rhythm credentials needs a web SSO key and the authorization code flow: the application sends the member to Rhythm’s hosted sign-in page at its authorization address, the member signs in there, and the application exchanges the code it receives at the token address for a token. This flow has to start in a browser, so it cannot run entirely from a script or a tool like Postman. A non-interactive key cannot do this by itself because there is no person to authenticate. If one external product needs both member sign-in and a separate background process that moves data, create two keys, one of each kind, instead of using one key for both jobs.
Before you request an authorization code, register the exact callback address your application uses on the key's address lists. An unregistered callback fails before it reaches your sign-in page. This is also what causes a "redirect URI" mismatch error when a microsite fails to open: the callback address on the key does not match the address the microsite is sending. Correcting the address list resolves the issue. Match the address exactly, including capitalization in the path, because a mismatched address is refused rather than treated as equivalent. After sign-in succeeds, decode the token you receive for Rhythm's own claims. The token carries a contact identifier after the member has signed in to the Portal at least once and has been linked to a contact record. It does not carry membership status, membership type, package, committee memberships, or certification status. To get those details, use the returned contact identifier in a separate API call.
A key belongs to one environment. A key you create in your live account and a key you create in your sandbox use separate identity-provider configurations, so a client identifier and secret from one never work in the other. If you need API access in both places, create a key in each.
The Secret Is Shown Once
When you create a key, or later rotate its secret, Rhythm does not show you the secret itself. Instead, Rhythm gives you a single-use link. Whoever opens that link, usually the developer you are working with, receives the secret exactly once. If anyone opens the same link again, it fails. After that one disclosure, the secret is never shown again in the Console, including on the key’s screen, in a list, or by visiting the same link again. The page that shows the one-time link also includes the client identifier and the identity-provider domain your integration needs for token requests, so save that information instead of copying only the link.
The link works only for a limited time, even if nobody opens it, and it stops working as soon as someone uses it once. If your developer does not open it in time, or the link is lost before anyone opens it, you cannot recover that secret. To restore access, rotate the key, which creates a new secret and a fresh one-time link.
Warning
Copy the link before you leave the page where it appears. Once you navigate away, Rhythm has no record of it. No list, detail view, or history shows the link again.
What You Can See About a Key Afterward
After a key exists, you can see its name and kind on the Manage API Keys list. On the key’s edit screen, you can see its name, description, and, for a web SSO key, its address lists. You can never see its secret again in the Console because reading, listing, and editing a key do not include the secret.
Machine Access Tokens
When an integration uses a non-interactive key to call Rhythm’s API, it exchanges the key’s client identifier and secret for a machine access token. This uses the OAuth 2.0 client credentials flow, which is the standard way software gets an access token when no person is signing in. The request is a POST to the identity-provider domain shown with your key, at its /oauth/token path. It must include grant_type=client_credentials, the client identifier, the client secret, and the audience https://api.rhythmsoftware.com. Send the request to that identity-provider domain, not to a general company sign-in page or the API host itself. A request sent to the wrong address usually comes back as a plain web page instead of a token, which points to the address being wrong rather than the credentials.
The integration then sends the token, not the key’s secret, with each API request. A machine access token is valid for 24 hours. Your integration should request one token and reuse it during that period instead of requesting a new token before every call. Rhythm does not offer a token that never expires, so an integration that needs to keep working indefinitely must refresh its token programmatically on this schedule instead of getting one token and keeping it forever. If your requests come back Unauthorized, first check whether the token you are sending has expired or is otherwise invalid before assuming something else is wrong.
Each account is limited to 1,000 machine-to-machine tokens per month. That limit is fixed, cannot be raised, and Rhythm Support cannot reset it mid-cycle. After you reach the limit, no more machine-to-machine tokens can be issued until the next month's allowance begins. This limit applies only to machine-to-machine tokens, not to tokens created when a person signs in. Requesting tokens too quickly can also trigger a shorter-window throttle before you reach the monthly limit. If your integration stops getting new tokens partway through the month, check whether it is requesting far more tokens than it needs, then start caching the tokens it already has. You can check your account's overall token usage, but usage is tracked at the account level and is not broken out by integration. If you see "There are too many requests right now" from the identity provider, that also points to a rate limit on sign-in traffic rather than a problem with your key.
The right client identifier and secret are not always enough by themselves. A client also needs to be authorized for the Rhythm API before token requests succeed. If a request is refused with a message that the client is not authorized to access the API, or needs a grant associated with it, the issue is this authorization step rather than a bad secret, and Rhythm can enable it on its side. When you diagnose a permission error on a specific API call, confirm that the call and the credentials behind it match the integration you are troubleshooting. A permission error on an unrelated call does not explain a different integration's problem.
Ordinary API access with a non-interactive key does not require your staging domain or IP address to be separately allowed. If calls are failing, review the actual error the API returns before assuming a whitelist is the cause. Rhythm's public developer documentation covers this authentication flow in more detail and includes guidance for investigating Unauthorized responses. If you need Rhythm to look deeper than the Console shows, such as at the identity provider's own logs, that investigation may need to be escalated internally and can take longer than a routine question.
Rotating and Revoking
If a key’s secret is lost, leaked, or shared with someone who should no longer have it, rotate the key instead of trying to recover the old secret. Rotation replaces the secret immediately. As soon as you confirm the rotation, the previous secret stops working for every system still using it, and Rhythm issues a new one-time link for the new secret.
Revoking a key removes it outright. After revocation, the partner system that held it can no longer act for your organization through that key, and the key no longer appears in your list.
A separate key for each integration, instead of one key shared across several, limits the damage if one integration's credentials are ever compromised. Rotating or revoking a shared key affects every system using it, while a dedicated key affects only the integration it was issued for. That said, nothing stops you from using one key for more than one integration if you would rather manage fewer credentials, such as one key for several similar portals. This is a tradeoff between convenience and isolation, not a rule. If the platform you want to connect to is not one Rhythm natively integrates with, you can still request a key for it and set up the connection yourself, the same way you would for any other custom integration.