docs: idp and auth var updates

packages/documentation/src/content/docs/integration/requirements/idp.mdx

@@ -12,7 +12,7 @@ import {
 
 An identity provider (IdP) is a system or service that stores and manages user identity information, authentication, and consent. Examples of IdPs include OpenID Connect and Okta.
 
-Open Payments requires any authorization server that issues interactive grants be integrated with an IdP. Interactive grants are used to gather consent. More information about interactive grants are available [below](#interactive-grants).
+Open Payments requires any authorization server that issues interactive grants be integrated with an IdP. Interactive grants are used to gather consent. More information about interactive grants is available [below](#interactive-grants).
 
 Responsibilities of your IdP include:
 - Providing an interface to gather end-user consent for a particular action
@@ -28,7 +28,7 @@ We provide Ory Kratos, a cloud-based user management system, for the identity an
 
 In Open Payments, grants are used to indicate a resource owner, such as an account holder, has given a piece of software, such as a mobile app, permission (consent) to act on their behalf. 
 
-Open Payments requires that consent is collected via an interactive grant before an <LinkOut href="https://openpayments.dev/introduction/op-concepts/#outgoing-payment">outgoing payments</LinkOut> request is issued. A grant is interactive when explicit interaction by an entity (e.g., the software's end user) is required to approve or deny the grant. Tapping an *Approve* button to authorize a payment is an example of an explicit interaction.
+Rafiki's implementation of an Open Payments authorization server requires that consent is collected via an interactive grant before an <LinkOut href="https://openpayments.dev/introduction/op-concepts/#outgoing-payment">outgoing payments</LinkOut> request is issued. A grant is interactive when explicit interaction by a resource owner (e.g., the software's end user) is required to approve or deny the grant. Tapping an *Approve* button to authorize a payment is an example of an explicit interaction.
 
 Interactive grants can be optional for incoming payments and quotes; however, they're enabled by default in Rafiki (the `LIST_ALL_ACCESS_INTERACTION` environment variable is `true`). When a grant request includes a `list-all` action for incoming payments and quotes, the request requires interaction. The `list-all` action is used when the client asks to list resources that it did not create.
 
@@ -40,7 +40,9 @@ See the <LinkOut href="https://openpayments.dev/introduction/grants/">Open Payme
 
 Authorization servers grant permission to clients to access the Open Payments Resource APIs. This enables clients to create incoming payments, quotes, and outgoing payments against an account holder's account.
 
-Rafiki's [auth service](/integration/services/auth-service) provides you with a reference implementation of an Open Payments authorization server. You can use the service as an alternative to developing your own in-house solution. Additionally, the server extends an [API](#interaction-endpoints) that provides interaction endpoints for your IdP.
+Rafiki's [auth service](/integration/services/auth-service) provides you with a reference implementation of an Open Payments authorization server. We recommend you use the `auth` service rather than developing your own in-house solution. 
+
+The authorization server also extends an [API](#interaction-endpoints) that provides interaction endpoints for your IdP.
 
 ### Environment variables
 
@@ -50,7 +52,7 @@ The following variables must be configured for the `auth` service.
 
 | Variable | Helm value name | Default | Description |
 | -------- | --------------- | ------- | ----------- |
-| `IDENTITY_SERVER_URL` | `auth.identityServer.domain` | N/A | The URL of your IdP's server, used by your authorization server to inform an Open Payments client of where to redirect the end-user to complete the interaction and authorize a grant. | Y | 
+| `IDENTITY_SERVER_URL` | `auth.identityServer.domain` | N/A | The URL of your IdP's server, used by the authorization server to inform an Open Payments client of where to redirect the end-user to start interactions. | Y | 
 | `IDENTITY_SERVER_SECRET` | `auth.identityServer.secret` | N/A | A shared secret between your authorization and IdP servers that your authorization server will use to secure its IdP-related endpoints.<br/>When your IdP sends requests to your authorization server, your IdP must provide the secret via an [`x-idp-secret`](#x-idp-secret-header) header. | Y |
 | `INCOMING_PAYMENT_INTERACTION` | `auth.interaction.incomingPayment` | `false` | Indicates whether incoming payments grant requests are interactive. | Y |
 | `INTERACTION_EXPIRY_SECONDS` | `auth.interactionExpirySeconds` | `600` | The time in seconds for which a user can interact with a grant request | Y |
@@ -92,21 +94,21 @@ We also provide an <LinkOut href="https://github.com/interledger/rafiki/blob/mai
 
 #### Start user interaction session
 
-Called by the client to establish an interactive session with your authorization server. Also redirects the client's browser session to your IdP consent screen.
+Called by the client to establish an interactive session with your authorization server. Your authorization server automatically redirects the request, via the URL defined in the `IDENTITY_SERVER_URL` variable, to your IdP consent screen.
 
 #### Look up grant information
 
 Called by your IdP server to retrieve a list of access rights, requested by the client, from your authorization server. The request is secured with an [`x-idp-secret`](#x-idp-secret-header) header. The access rights are presented to the client's end-user on the consent screen. The authorization server's response is served on your configured `INTERACTION_PORT`.
 
 #### Accept or reject grant
 
-Your IdP server communicates the choice made by the end-user on the consent screen (accept/reject) to your authorization server. The request is secured with an [`x-idp-secret`](#x-idp-secret-header) header. Then, your IdP server calls the `finish` endpoint on Rafiki's `auth` service, which handles the interaction requests on your defined `INTERACTION PORT`.
+Your IdP server communicates the choice made by the end-user on the consent screen (accept/reject) to your authorization server. The request is secured with an [`x-idp-secret`](#x-idp-secret-header) header. Your authorization server responds to your IdP server, acknowledging that it received the quest.
 
 #### Finish interaction
 
-Called by your IdP server to end the interaction and redirect the end-user's browser session to the URI of the <LinkOut href="https://openpayments.dev/apis/auth-server/operations/post-request/">grant initialization request</LinkOut>.
+Called by your IdP server to end the interaction. Your authorization server automatically redirects the end-user's browser session to the `finish` endpoint on Rafiki's `auth` service, which handles the interaction requests on your defined `INTERACTION PORT`.
 
-The `result` query parameter indicates the success or failure of the grant authorization. The following are examples of the possible response types.
+The `result` query parameter in the response indicates the success or failure of the grant authorization. The following are examples of the possible response types.
 
 <div class="overflow-table wider-column">
 
@@ -118,7 +120,7 @@ The `result` query parameter indicates the success or failure of the grant autho
 
 </div>
 
-When successful, the SHA-256 hash of the interaction is sent in the response to the client, along with an `interact_ref` that identifies the interaction on the authorization server and the URI of the grant initialization request. The client must verify the hash before it will request to continue the grant
+When successful, the SHA-256 hash of the interaction is sent in the response to the client, along with an `interact_ref` that identifies the interaction on the authorization server and the URI of the grant initialization request. The client must verify the hash before it will request to continue the grant.
 
 #### Continue grant