Authentication

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 support@rhythmsoftware.com.

Flows

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.

Authorization Header

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.

Isolation

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:

Bearer access_token

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.

info

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

attention

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.

warning

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:

https:// auth0 domain/oauth/token

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 SDKs

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

First Call

Don't forget to specify your Authorization header as "Bearer access_token". If your access_token and tenantId are valid, you will receive a JSON response.