# Concepts These concepts are commonly used throughout the Rhythm API. They are useful to understand before exploring guides or references for specific APIs. ## Tokens Rhythm's API will accept either tokens generated for a specific user (**user access tokens**), or a token generated for automated machine-to-machine scripts (**M2M access tokens**). There is a monthly limit on the number of M2M access tokens you may generate across all your integrations (1,000). If you exceed this limit, you will not be able to issue any M2M tokens until the next month, which may cause your integrations to fail. Tokens are valid for 24 hours, so they should be securely cached and reused during that period to reduce consumption. When properly cached, each application using the Rhythm API should only be using a maximum of 31 M2M access tokens per month. This limit does not apply to the other authorization flows where a user is interactively entering credentials (see below). You should **never** create a new M2M access token for each user login. Because of the **limit on M2M tokens**, you should instead use a **user access token** whenever you are accessing the Rhythm API on behalf of a user who has logged in interactively. If a user is asked to enter their credentials, you should use the Authorization Code flow whenever possible. If your application cannot support redirecting the user and **must** receive user credentials directly, you may instead use the Resource Owner Password flow to generate a **user access token** using an API call. In this case, please reach out to Rhythm by creating a support request in [ZenDesk](https://support.rhythmsoftware.com) so this option can be enabled for your API credentials. M2M access tokens are only appropriate for scenarios where no interactive user is logged in, such as automated, recurring jobs, or bulk data operations. Because API calls are being executed by a system with no interactive user, you should be able to securely cache and reuse a single M2M token for 24 hours. For more information see the section on [authentication](/tutorials/authentication). ## Users vs. Contacts A User and a Contact are distinct but related records. A Contact exists in the [Rolodex (Contacts & Organizations)](/apis/rolodex/rolodex-v1) app and contains all demographic information. When a member joins, renews, registers, pays, or otherwise interacts with the Rhythm Portal, all of this information is related to their Contact record. A User may be thought of as an identity, or as login credentials, that may come from a variety of systems external to Rhythm (Google, Facebook, LinkedIn, etc). A Contact record may be related to one or more Users. Duplicate Prevention One member may create multiple Users by logging in with LinkedIn, then Google, then Facebook, and link all of these Users to the same Contact. Because all records in Rhythm are related to the Contact, when the member logs in to the Rhythm Portal, they will always see the same information regardless of which User account they use for authentication. This User + Contact link is established the first time a User logs into the Rhythm Portal. The related Contact ID is added to the User metadata and can later be retrieved from any JSON Web Token (JWT) issued for the user. For more information see [authentication](/tutorials/authentication) or [SSO guide](/guides/sso). ## Requests Most requests require a `tenantId` parameter passed in the URI. This value identifies the Rhythm tenant the API call is being executed against. If you do not know your tenantId, please log a support request in [ZenDesk](https://support.rhythmsoftware.com). Multi-Tenant For multi-tenant integrations, you must supply the `tenantId` that is applicable for the current request. Every request to the Rhythm API requires an HTTP Header called `Authorization` which is examined to allow or deny the request. In the [authentication](/tutorials/authentication) section, we will see how to retrieve an **access token** for a user to make API calls on their behalf. Denied If you submit a request for a tenantId the user is not authorized to access, **or to a URI that does not match any endpoint**, your request will be denied. Many requests also require a `contactId` value passed in the URI. In most cases, this is the contactId for the user who initiated the API request, which you can extract from the authenticated **user access token**. ## Responses Most of the endpoints in the Rhythm API return a single record or item. However, some long-running tasks, such as **queries** will instead return an identifier that you can use to check the progress of the task. For an example, see the [query guide](/guides/query). Other tasks, such as processing an Order, Invoice, or Payment, will return an `executionArn` which can be used in the [System API > Step Functions](/apis/system/system-v1/step-functions) API to check on the status of these tasks. ### Paging When an endpoint may return many records or items, rather than just returning an array, it will return the results in an `Items` attribute along with `Count` and `LastEvaluatedKey` attributes. The `LastEvaluatedKey` can be returned to the same endpoint using the `exclusiveStartKey` query string parameter to get the next page of results. Rate Limits Looping through a large number of pages programmatically may cause you to exceed API rate limits. Instead, use a **query** to retrieve all items at once as *described below*. ## Retrieving Multiple Items The Rhythm API uses three patterns for retrieving multiple items in a single request & response. | Capability | List | Search | Query | | --- | --- | --- | --- | | Specify return fields | Yes | Yes | Yes | | Paged results | Yes | Yes | No | | Filter results | No | Yes | Yes | | Complex criteria | No | No | Yes | | Fields from related types | No | No | Yes | | Multiple return formats | No | No | Yes | ### List The simplest are **lists** which are `GET` endpoints that return a simple JSON `array` of items. These endpoints do not have the option to supply custom criteria. Examples of list endpoints might be [listAddressTypes](/apis/rolodex/rolodex-v1/address-types/listaddresstypes) or [getUpcomingEvents](/apis/events/events-v1/events/getupcomingevents). Fields Like most `GET` endpoints, you can supply field names in the query string to limit the response size, which can be very useful for client-side javascript or mobile clients. ### Search A **search** is a strongly typed `POST` endpoint which defines preset criteria options you can supply in the `body` to change the search parameters. These endpoints return a JSON response which may contain `Count`, `Items`, and `LastEvaluatedKey` attributes. The `Items` attribute will be an `array` containing **one page** of the items that match **all** the criteria you supplied (see **Paging** above). Examples of search endpoints might be [searchForContacts](/apis/rolodex/rolodex-v1/contacts/searchforcontacts) or [searchForEvents](/apis/events/events-v1/events/searchforevents). ### Query A **query** uses multiple `POST` and `GET` endpoints. The same endpoints are used to initiate a query regardless of the type of record being returned. A query will return a JSON response with a signed URI where you can download a loosely typed dataset containing **all** the items that match the criteria. Flexible Query is the most flexible method for retrieving multiple items. With a Query you can: * Define criteria with advanced `any` or `all` grouping, nested groups, and a variety of operators. * Return results in `json`, `csv`, `excel`, or another data type you specify. * Use return and criteria fields from multiple types, or multiple apps, within the same query. To learn more about queries see the [Query Guide](/guides/query). ## What's Next Head over to the [Authentication](/tutorials/authentication) section to learn about the different authentication flows the Rhythm APIs support.