# grove.oauth.prepare()

Prepare host-owned state and PKCE for a brokered authorization flow.

## Signature

```ts
grove.oauth.prepare(): Promise<{
  readonly transactionID: string; readonly redirectURI: string
  readonly state: string; readonly codeChallenge: string
  readonly codeChallengeMethod: 'S256'
}>
```

## Availability

Runtime with oauth.authorize. Settings pages cannot use OAuth. The later authorization and service requests need their own accepted HTTPS destinations.

## Parameters

None.

## Return value

Resolves to a frozen transaction object. transactionID identifies the pending transaction in this document; redirectURI is mango://grove/oauth; state is a random value; codeChallenge is the base64url S256 PKCE challenge. The verifier is not returned.

## Behavior and errors

Does not open a browser or contact the service. A new preparation replaces this instance's unused preparation. An active authorization session in this instance rejects preparation. Pass transactionID to authorize to consume the preparation; it is not durable across document reload or stop. The authorization session remains app-wide exclusive.

Preparation only generates transaction material; it does not verify a broker uses it. The broker must preserve the returned redirectURI, state, codeChallenge, and codeChallengeMethod in its provider request and enforce PKCE at exchange. Read the [broker trust boundary](grove-oauth-authorize.md#behavior-and-errors) before using this flow.

## Example

```js
try {
  const transaction = await grove.oauth.prepare()
  // Send redirectURI, state and codeChallenge to your broker's start API.
  console.info('Authorization transaction prepared')
} catch {
  console.error('Could not prepare authorization.')
}
```

See [grove.oauth.authorize()](grove-oauth-authorize.md) and the complete [brokered flow](oauth.md#brokered-pkce).