# Authenticating and sending data via Redox To open the data traffic highway, so to speak, you must first authenticate your system to Redox. > **Authenticating your incoming data** > > Just like we check _your_ requests to us are valid, you should also verify data coming in to your system. [Learn about authenticating incoming data](/basics/data-exchange-with-redox/receiving-data-from-redox). ## What is authentication? **Authentication** is the process of proving your system’s identity to Redox. Before you can send data, you must authenticate to establish a secure, trusted connection. You can use these authentication methods for these communication method types: | **Communication method** | **How to authenticate** | | --- | --- | | API | OAuth API key (_recommended_) or legacy API key | | SFTP | Username and password assigned by the SFTP server | | MLLP | VPN configuration | ## Why is authentication necessary? Think of authentication like a digital secret handshake. By presenting valid authentication, your system tells Redox, “I am who I say I am, and you can trust the data I’m about to send.” This process is essential for securing protected health information (PHI) and ensuring data is only sent from authorized sources. ## How API authentication works An **OAuth API key** includes an ID and a public key/private key pair. A **legacy API key** includes an ID and a secret value. The IDs are assigned by Redox, and you can generate a private key/public key pair or secret value in the Redox dashboard. When you send an authentication request with the correct private key or secret value, we generate an **access token** that’s good for 5 minutes. The access token allows you to initiate requests (e.g., `SEND` or `REQUEST`). > **Keep your secrets safe** > > You should keep your private key or secret secure. Don’t ever expose these values to a client with your production data. ### Two methods of API authentication You have two options for authenticating your API requests:
OAuth API key (recommended) An OAuth API key relies on the following standards to authorize your system (instead of an individual user and source) to Redox: - OAuth 2.0 - JSON web token (JWT) - SMART backend services. Redox verifies the stored information in the JWT, which means staff or device changes won’t affect authorization requests. > **Reference material for authentication standards** > > If you want more of a conceptual summary, [learn how OAuth works](https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth) or [watch this YouTube tutorial on JWT](https://www.youtube.com/watch?v=7Q17ubqLfaM). > > If you’re familiar with the basics of JWT but you want a technical reference, [check out this Request for Comments (RFC) on JWT](https://datatracker.ietf.org/doc/html/rfc7519). > > _Pro tip_: JWT is an implementation of SMART backend services authorization. Any tools that conform to SMART backend services should work with this authorization method. [Learn more about SMART backend services authorization](https://build.fhir.org/ig/HL7/bulk-data/authorization.html). We support the OAuth method for all of our available APIs, but the scopes are different: - Redox FHIR API and Redox Data Model API: These APIs use organization-level keys, meaning authorization and resulting permissions are based on the organization or system. [Learn how to authenticate an OAuth API key](/api-reference/redox-data-model-api/authenticate-an-oauth-api-key). - Redox Platform API: This API uses user-level keys, meaning authorization and resulting permissions are based on the individual requesting user. Some API functionalities might be restricted, depending on the individual user’s permissions. [Learn how to authenticate a user-level API key](/api-reference/platform-api/authenticate-a-user-level-api-key). > **Where to find OAuth API keys** > > There are two places to manage OAuth API keys in the Redox dashboard. You can find organization-level API keys (for the FHIR API or Data Model API) on the Developer \> Sources page of the dashboard. Or, you can find user-level keys (for the Platform API) under the user menu settings. #### Requesting new access tokens Once you authenticate an OAuth API key, you receive an access token that’s valid for 5 minutes. You can initiate requests during that window with the access token. To continue initiating requests after that window, you must request a new access token. We don’t support refresh tokens. However, we recommend requesting access tokens based on your traffic volume: - For low traffic, request an access token before making any API requests. - For high traffic, get as many access tokens as you need. Then, use different access tokens for multiple API requests.
Legacy API key Legacy API keys rely on the Redox server to store user information with a session ID and cookies to authorize user access. A legacy API key can only authorize one source. > **Legacy method** > > This type of API key has been deprecated, so it may not be available to you if you joined Redox after 2023. We support this authentication method for the Redox Data Model API and the Redox FHIR API. [Learn how to authenticate a legacy API key](/how-to-use-redox/manage-your-redox-setup/authenticate-a-legacy-api-key). #### Requesting new access tokens or using refresh tokens Once you authenticate a legacy API key, you receive an access token that validates requests from the source for 24 hours. Store your authentication token securely and use it for all requests within that 24-hour period. We recommend requesting access tokens based on your traffic volume: - For low traffic, request a new access token after the 24-hour period expires to continue making API requests. - For high traffic, run a separate service to generate a new token with the refresh token after the 24-hour period expires. Using a separate service is best if you don’t want to disrupt routine workflows by generating a new token daily. > **Refresh token expiration** > > Refresh tokens are dynamic, so they change and rotate daily. They expire after 7 days of inactivity. > > However, we recommend requesting new access tokens rather than managing refresh tokens. This simplifies your workflow and avoids the risk of accidentally leaking a secret value.
> **Authentication for TEFCA** > > If using Network Onramps to connect with TEFCA, you’re responsible for using access tokens that have timeouts shorter than 1 day. Be sure to use our recommended OAuth API keys for authenticating your API requests to TEFCA. [Learn more about TEFCA](/how-to-use-redox/interact-with-clinical-networks/onramp-to-tefca-commonwell). ### Access control with multiple API keys We recommend having at least one API key for each environment type (i.e., development, staging, production). However, you can create multiple API keys for an environment, depending on how you want to control access. It just depends on your organization’s security practices. For example, if two dev teams work in the same environment, it may be useful to have different API keys for each team to work in their own context. Users in your organization can view or manage API keys depending on their assigned environment role. [Learn about environment roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles). > **Multiple API keys for the Redox Data Model API** > > _If using multiple OAuth API keys and sources per environment_, the `Meta.Source.ID` field is required in all of your outgoing Redox Data Model API requests. This is because OAuth API keys are organization-level keys, not source-specific. Redox uses the source ID field to distinguish which source initiated the message to route data appropriately. > > _If using multiple legacy API keys per environment_, the `Meta.Source.ID` field is optional. This is because legacy API keys are source-specific, not organization-level. > > As a reminder, a source identifies the communication method and sending system. [Learn more about managing source details in outgoing requests](/basics/data-exchange-with-redox/Managing-source-details-in-outgoing-requests). > **For multi-region organizations** > > The source you use designates which region an API request comes from. As best practice for security, though, we recommend using a unique OAuth API key for sources in each region. > > You can designate the region the API key name (e.g., `Production API key — U.S.`). ## What to expect from responses After receiving an access token, you’re ready to initiate requests. But initiating is just one side of the exchange. Responses differ based on the request type. Check out these articles to learn about handling your connection’s responses or responding to requests from your connection: - [Responding to asynchronous events](/basics/data-exchange-with-redox/handling-notifications-and-responses) - [Responding to queries](/basics/data-exchange-with-redox/responding-to-queries)