This API uses the OpenID Connect (OIDC) Protocol and the OAuth 2.0 Authorization Framework, through Auth0, for authentication. Auth0 supports a wide variety of authentication use-cases including Multi-Factor Authentication (MFA), Social Login, Federated Identity, Single Sign-On, etc.
To authenticate you will need a Client ID, Secret, and the Auth0 domain for the tenant you will be accessing. All of this information can be requested from firstname.lastname@example.org.
You will use this information to complete one of the authentication flows described below.
Which flow you will use depends on how you plan on using the API.
Before you start, please be sure to review all the information in the concepts section.
Once you complete one of the authentication flows below, you will receive an access token which you can send to the Rhythm API to authorize each request.
Access tokens are Base64 encoded JSON Web Tokens (JWTs) that automatically expire, and are specific to the user who has authenticated.
Tokens generated using the Client Credentials flow may be securely cached, but tokens generated by an interactive user should be restricted to the authenticated user's session.
To authorize each API request, pass the access token in the Authorization HTTP header with a value in the format:
Authorization Code Flow
This is the most common method of authentication for standard websites and other server-side integrations, when there is an interactive user whose actions initiate API calls, and the source code is not publicly exposed.
The flow starts with a redirect to Auth0, which includes your client ID and your return URL.
After authentication, users will be redirected back to your return URL with a code you can use to get with their access token.
To learn more about the authorization code flow, see: https://auth0.com/docs/flows/authorization-code-flow
For detailed instructions on generating an access token using the Authorization Code Flow, see the Rhythm Single Sign On Quick Start document.
Authorization Code with PKCE
For mobile/native apps or single page apps (SPAs) you will use the Authorization Code Flow with Proof Key for Code Exchange (PKCE).
This flow is different from server-side websites because the authentication starts on the user's device.
This gives the user access to your source code, and you cannot securely store a secret on their device.
To learn more about the authorization code flow with PKCE, see: https://auth0.com/docs/authorization/flows/authorization-code-flow-with-proof-key-for-code-exchange-pkce
Client Credentials Flow
This flow is typically used by scripts and other automated server-side processes that periodically run API calls. These programs often use the Query APIs to retrieve and cache data. This data may then be delivered by your APIs to your users.
There is a monthly limit on the number of access tokens you may retrieve using this flow.
Tokens are valid for 24 hours, so they should be securely cached.
This limit does not apply to the other authorization flows.
To learn more about the Client Credentials flow see: https://auth0.com/docs/authorization/flows/client-credentials-flow
Obtaining an access token using the Client Credentials flow only requires one x-www-form-urlencoded POST to:
Your POST should include the following information in the body:
grant_type=“client_credentials” &client_id=[your client id] &client_secret=[your client secret] &audience=“https://api.rhythmsoftware.com”
This endpoint is described further here: https://auth0.com/docs/api/authentication?http#authenticate-user
Auth0 publishes SDKs for several popular frameworks which you can use instead of manually executing an authorization flow.
For a full list, see https://auth0.com/docs/libraries
Don't forget to specify your
Authorization header as "Bearer
access_token". If your
tenantId are valid, you will receive a JSON response.