### Install Dependencies and Start Server

Source: https://github.com/simov/grant/blob/master/examples/README.md

Installs project dependencies using npm and starts the Node.js server. This is typically the first step before running the application.

```bash
$ npm install
$ node app.js
```

--------------------------------

### Configuration: Basics

Source: https://github.com/simov/grant/blob/master/README.md

Provides examples of basic configuration for Grant, including default settings and provider-specific options for Google and Twitter.

```APIDOC
## Configuration: Basics

### Description
Basic configuration structure for Grant, including defaults and provider-specific settings.

### Parameters
#### Request Body
- **defaults** (object) - Optional - Default configuration for all providers.
  - **origin** (string) - Optional - The origin URL of your client server.
  - **transport** (string) - Optional - The transport mechanism for response data.
  - **state** (boolean) - Optional - Whether to generate a random state string.
- **provider** (object) - Required - Configuration for a specific OAuth provider (e.g., 'google', 'twitter').
  - **key** (string) - Required - The consumer key or client ID for the OAuth app.
  - **secret** (string) - Required - The consumer secret or client secret for the OAuth app.
  - **scope** (array) - Optional - An array of OAuth scopes to request.
  - **nonce** (boolean) - Optional - Whether to generate a random nonce string (OpenID Connect only).
  - **custom_params** (object) - Optional - Custom authorization parameters.
  - **callback** (string) - Optional - The relative route or absolute URL to receive response data.

### Request Example
```json
{
  "defaults": {
    "origin": "http://localhost:3000",
    "transport": "session",
    "state": true
  },
  "google": {
    "key": "...",
    "secret": "...",
    "scope": ["openid"],
    "nonce": true,
    "custom_params": {"access_type": "offline"},
    "callback": "/hello"
  },
  "twitter": {
    "key": "...",
    "secret": "...",
    "callback": "/hi"
  }
}
```
```

--------------------------------

### Dynamic Configuration Override Example (URL)

Source: https://github.com/simov/grant/blob/master/README.md

An example of making a GET request to dynamically set the 'subdomain' for the Shopify provider, overriding any existing configuration.

```text
https://awesome.com/connect/shopify?subdomain=usershop
```

--------------------------------

### Fastify Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Integrates Grant with Fastify. Requires @fastify/cookie and @fastify/session for session management. Registers cookie, session, and Grant plugins.

```javascript
var fastify = require('fastify')
var cookie = require('@fastify/cookie')
var session = require('@fastify/session')
var grant = require('grant').fastify()

fastify()
  .register(cookie)
  .register(session, {secret: 'grant', cookie: {secure: false}})
  .register(grant({/*configuration - see below*/}))
```

--------------------------------

### Express Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Integrates Grant with Express. Requires express-session for session management. Mounts the Grant middleware after session initialization.

```javascript
var express = require('express')
var session = require('express-session')
var grant = require('grant').express()

var app = express()
// REQUIRED: any session store - see /examples/handler-express
app.use(session({secret: 'grant'}))
// mount grant
app.use(grant({/*configuration - see below*/}))
```

--------------------------------

### Koa Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Integrates Grant with Koa. Requires koa-session for session management. Sets app.keys for session signing and mounts the Grant middleware.

```javascript
var Koa = require('koa')
var session = require('koa-session')
var grant = require('grant').koa()

var app = new Koa()
// REQUIRED: any session store - see /examples/handler-koa
app.keys = ['grant']
app.use(session(app))
// mount grant
app.use(grant({/*configuration - see below*/}))
```

--------------------------------

### Hapi Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Integrates Grant with Hapi. Requires yar for session management. Registers the yar session plugin and the Grant plugin with the server.

```javascript
var Hapi = require('hapi')
var yar = require('yar')
var grant = require('grant').hapi()

var server = new Hapi.Server()
server.register([
  // REQUIRED: any session store - see /examples/handler-hapi
  {plugin: yar, options: {cookieOptions: {password: 'grant', isSecure: false}}},
  // mount grant
  {plugin: grant({/*configuration - see below*/})}
])
```

--------------------------------

### Custom Provider Configuration Example (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Defines a custom OAuth provider named 'awesome' by specifying all required details like 'authorize_url', 'access_url', 'key', 'secret', and 'scope'.

```json
{
  "defaults": {
    "origin": "http://localhost:3000"
  },
  "awesome": {
    "authorize_url": "https://awesome.com/authorize",
    "access_url": "https://awesome.com/token",
    "oauth": 2,
    "key": "...",
    "secret": "...",
    "scope": ["read", "write"]
  }
}
```

--------------------------------

### Enable Request Logs

Source: https://github.com/simov/grant/blob/master/README.md

Installs 'request-logs' for debugging and enables request logging via the DEBUG environment variable. Logs include request, response, and JSON data.

```bash
npm i --save-dev request-logs
DEBUG=req,res,json node app.js
```

--------------------------------

### Grant v5 Handler Constructors (JavaScript)

Source: https://github.com/simov/grant/blob/master/MIGRATION.md

Grant v5 changes how framework handlers (Express, Koa, Hapi) are required. It now uses a unified `grant` module with specific constructors or a configuration object.

```javascript
var grant = require('grant').express()(config)
var grant = require('grant').express()({config, ...})
var grant = require('grant').express(config)
var grant = require('grant').express({config, ...})
var grant = require('grant')({handler: 'express', config})
```

--------------------------------

### Configure Sandbox OAuth URLs

Source: https://github.com/simov/grant/blob/master/README.md

JSON examples for overriding OAuth URLs to use sandbox environments for providers like PayPal and Evernote. Includes 'request_url', 'authorize_url', and 'access_url'.

```json
"paypal": {
  "authorize_url": "https://www.sandbox.paypal.com/webapps/auth/protocol/openidconnect/v1/authorize",
  "access_url": "https://api.sandbox.paypal.com/v1/identity/openidconnect/tokenservice"
},
"evernote": {
  "request_url": "https://sandbox.evernote.com/oauth",
  "authorize_url": "https://sandbox.evernote.com/OAuth.action",
  "access_url": "https://sandbox.evernote.com/oauth"
}
```

--------------------------------

### Vercel Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Sets up Grant for Vercel. Takes configuration and session secrets. The handler processes the request and response objects, returning a JSON response.

```javascript
var grant = require('grant').vercel({
  config: {/*configuration - see below*/}, session: {secret: 'grant'}
})

module.exports = async (req, res) => {
  var {response} = await grant(req, res)
  if (response) {
    res.statusCode = 200
    res.setHeader('content-type', 'application/json')
    res.end(JSON.stringify(response))
  }
}
```

--------------------------------

### Form Body Parser Middleware Configuration (JavaScript)

Source: https://github.com/simov/grant/blob/master/README.md

JavaScript code examples showing how to configure body-parser middleware for Express, Koa, and Fastify to handle form submissions for dynamic configuration.

```javascript
// Express
.use(require('body-parser').urlencoded({extended: true}))
```

```javascript
// Koa
.use(require('koa-bodyparser')())
```

```javascript
// Fastify
.register(require('@fastify/formbody'))
```

--------------------------------

### Azure Function Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Sets up Grant for Azure Functions. Takes configuration and session secrets. The handler processes the request, returning a redirect or a JSON response.

```javascript
var grant = require('grant').azure({
  config: {/*configuration - see below*/}, session: {secret: 'grant'}
})

module.exports = async (context, req) => {
  var {redirect, response} = await grant(req)
  return redirect || {
    status: 200,
    headers: {'content-type': 'application/json'},
    body: JSON.stringify(response)
  }
}
```

--------------------------------

### AWS Lambda Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Sets up Grant for AWS Lambda. Takes configuration and session secrets. The handler processes the event, returning a redirect or a JSON response.

```javascript
var grant = require('grant').aws({
  config: {/*configuration - see below*/}, session: {secret: 'grant'}
})

exports.handler = async (event) => {
  var {redirect, response} = await grant(event)
  return redirect || {
    statusCode: 200,
    headers: {'content-type': 'application/json'},
    body: JSON.stringify(response)
  }
}
```

--------------------------------

### Grant v5 Origin Configuration (JSON)

Source: https://github.com/simov/grant/blob/master/MIGRATION.md

Grant v5 deprecates the separate `protocol` and `host` configurations. It recommends using the unified `origin` configuration to define the client server's origin.

```json
{
  "defaults": {
    "origin": "http://localhost:3000"
  }
}
```

--------------------------------

### Configure Subdomain URLs for OAuth Providers

Source: https://github.com/simov/grant/blob/master/README.md

Example JSON configuration for setting subdomain tokens in OAuth provider settings. This dynamically generates correct OAuth URLs for services like Shopify and Battle.net.

```json
"shopify": {
  "subdomain": "mycompany"
},
"battlenet": {
  "subdomain": "us"
}
```

```json
"shopify": {
  "authorize_url": "https://mycompany.myshopify.com/admin/oauth/authorize",
  "access_url": "https://mycompany.myshopify.com/admin/oauth/access_token"
},
"battlenet": {
  "authorize_url": "https://us.battle.net/oauth/authorize",
  "access_url": "https://us.battle.net/oauth/token"
}
```

--------------------------------

### Google Cloud Function Handler Setup

Source: https://github.com/simov/grant/blob/master/README.md

Sets up Grant for Google Cloud Functions. Takes configuration and session secrets. The handler processes the request and response objects, returning a JSON response.

```javascript
var grant = require('grant').gcloud({
  config: {/*configuration - see below*/}, session: {secret: 'grant'}
})

exports.handler = async (req, res) => {
  var {response} = await grant(req, res)
  if (response) {
    res.statusCode = 200
    res.setHeader('content-type', 'application/json')
    res.end(JSON.stringify(response))
  }
}
```

--------------------------------

### Configure Custom Parameters for OAuth Providers

Source: https://github.com/simov/grant/blob/master/README.md

Allows providers to use custom authorization parameters, enhancing flexibility. Examples include 'access_type' for Google and 'duration' for Reddit.

```json
{
  "google": {
    "custom_params": {"access_type": "offline", "prompt": "consent"}
  },
  "reddit": {
    "custom_params": {"duration": "permanent"}
  },
  "trello": {
    "custom_params": {"name": "my app", "expiration": "never"}
  }
}
```

--------------------------------

### Grant v5 Prefix Configuration for OAuth Path (JSON)

Source: https://github.com/simov/grant/blob/master/MIGRATION.md

Grant v5 replaces the `path` configuration with `prefix` for setting a path prefix. This change simplifies the configuration for OAuth connect endpoints.

```json
{
  "defaults": {
    "origin": "http://localhost:3000",
    "prefix": "/oauth/connect"
  }
}
```

--------------------------------

### Configure Callback Transport as Session

Source: https://github.com/simov/grant/blob/master/README.md

Configures Grant to store OAuth response data in the session object. This is recommended for local callback routes and provides examples for different frameworks.

```json
{
  "defaults": {
    "transport": "session"
  },
  "github": {
    "callback": "/hello"
  }
}
```

--------------------------------

### Grant v5 Response Configuration for JWT (JSON)

Source: https://github.com/simov/grant/blob/master/MIGRATION.md

Grant v5 requires explicit configuration to return decoded JWTs. The `response` array can include 'jwt' to enable this. Previously, 'jwt' was implicitly handled.

```json
{
  "google": {
    "response": ["tokens", "raw", "jwt"]
  }
}
```

--------------------------------

### Grant v5 JWT Access in Response (JavaScript)

Source: https://github.com/simov/grant/blob/master/MIGRATION.md

When the 'jwt' option is used in Grant v5's response configuration, the decoded JWT is made available under `jwt.id_token`. This replaces the v4 behavior of `id_token_jwt`.

```javascript
{
  id_token: '...',
  access_token: '...',
  refresh_token: '...',
  raw: {
    id_token: '...', 
    access_token: '...', 
    refresh_token: '...', 
    some: 'other data'
  },
  jwt: {id_token: {header: {}, payload: {}, signature: '...'}}
}
```

--------------------------------

### Grant v5 id_token Default Return (JavaScript)

Source: https://github.com/simov/grant/blob/master/MIGRATION.md

In Grant v4, id_token was returned decoded by default. Grant v5 returns id_token as a string by default. This change impacts how you access JWT claims.

```javascript
{
  id_token: 'abc.abc.abc',
  access_token: '...',
  refresh_token: '...'
}
```

--------------------------------

### Grant Handler Instantiation (JavaScript)

Source: https://github.com/simov/grant/blob/master/README.md

Demonstrates various ways to instantiate the Grant middleware for different frameworks like Express, Koa, and Fastify, including using the 'new' keyword and passing configuration in different orders.

```javascript
// Express or any other handler
var grant = require('grant').express()(config)
var grant = require('grant').express()({config, ...})
var grant = require('grant').express(config)
var grant = require('grant').express({config, ...})
var grant = require('grant')({handler: 'express', config, ...})
```

```javascript
// Using 'new' keyword is optional
var Grant = require('grant').express()
var grant = Grant(config)
var grant = new Grant(config)
```

```javascript
// Hapi
server.register([{plugin: grant(config)}])
server.register([{plugin: grant(), options: config}])
```

--------------------------------

### Configuration: Description

Source: https://github.com/simov/grant/blob/master/README.md

Details the configuration options available for Grant, categorized by Authorization Server, Client Server, Client App, and Grant itself.

```APIDOC
## Configuration: Description

### Description
Provides a detailed breakdown of all configuration options for the Grant middleware, categorized for clarity.

### Parameters
#### Request Body
- **`request_url`** (string) - Optional - OAuth 1.0a only, the initial request token URL.
- **`authorize_url`** (string) - Optional - The URL for the authorization step.
- **`access_url`** (string) - Optional - The URL for the access token step.
- **`oauth`** (string) - Optional - The OAuth version number.
- **`scope_delimiter`** (string) - Optional - The delimiter used for concatenating scopes.
- **`token_endpoint_auth_method`** (string) - Optional - Authentication method for the token endpoint.
- **`token_endpoint_auth_signing_alg`** (string) - Optional - Signing algorithm for the token endpoint.
- **`origin`** (string) - Optional - Where your client server can be reached.
- **`prefix`** (string) - Optional - Path prefix for Grant internal routes.
- **`state`** (boolean) - Optional - Whether to generate a random state string for OAuth 2.0.
- **`nonce`** (boolean) - Optional - Whether to generate a random nonce string for OpenID Connect.
- **`pkce`** (boolean) - Optional - Toggle PKCE support.
- **`response`** (string) - Optional - Specifies the response data format.
- **`transport`** (string) - Optional - The method for delivering response data.
- **`callback`** (string) - Optional - The URL to receive response data.
- **`overrides`** (object) - Optional - Static configuration overrides for a provider.
- **`dynamic`** (object) - Optional - Configuration keys that can be dynamically overridden.
- **`key` / `client_id` / `consumer_key`** (string) - Required - The `client_id` or `consumer_key` of your OAuth app.
- **`secret` / `client_secret` / `consumer_secret`** (string) - Required - The `client_secret` or `consumer_secret` of your OAuth app.
- **`scope`** (array) - Optional - List of scopes to request.
- **`custom_params`** (object) - Optional - Custom authorization parameters and their values.
- **`subdomain`** (string) - Optional - String to embed into authorization server URLs.
- **`public_key`** (string) - Optional - Public PEM or JWK for signing.
- **`private_key`** (string) - Optional - Private PEM or JWK for signing.
- **`redirect_uri`** (string) - Optional - The absolute redirect URL of the OAuth app.
- **`name`** (string) - Optional - The provider's name.
- **`[provider]`** (object) - Optional - Provider-specific configurations keyed by provider name.
- **`profile_url`** (string) - Optional - User profile URL.
```

--------------------------------

### Basic Grant Configuration

Source: https://github.com/simov/grant/blob/master/README.md

This JSON snippet demonstrates the basic configuration structure for the Grant library, including default settings and provider-specific configurations for Google and Twitter.

```json
{
  "defaults": {
    "origin": "http://localhost:3000",
    "transport": "session",
    "state": true
  },
  "google": {
    "key": "...",
    "secret": "...",
    "scope": ["openid"],
    "nonce": true,
    "custom_params": {"access_type": "offline"},
    "callback": "/hello"
  },
  "twitter": {
    "key": "...",
    "secret": "...",
    "callback": "/hi"
  }
}
```

--------------------------------

### Connect: Prefix

Source: https://github.com/simov/grant/blob/master/README.md

Explains how to configure the default prefix for Grant routes.

```APIDOC
## Connect: Prefix

Grant operates on two primary routes by default:

- `/connect/:provider/:override?`
- `/connect/:provider/callback`

The default `/connect` prefix can be customized.

### Example
```json
{
  "defaults": {
    "origin": "http://localhost:3000",
    "prefix": "/oauth"
  }
}
```

With this configuration, the routes would become `/oauth/:provider/:override?` and `/oauth/:provider/callback`.
```

--------------------------------

### Dynamic Shopify Subdomain Configuration (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

This JSON snippet demonstrates how to configure the 'subdomain' key dynamically for the Shopify provider. It allows the subdomain to be set via HTTP requests.

```json
{
  "shopify": {
    "dynamic": ["subdomain"]
  }
}
```

--------------------------------

### Configuration: Values

Source: https://github.com/simov/grant/blob/master/README.md

Details the various configuration values for Authorization Server, Client Server, Client App, and Grant.

```APIDOC
## Configuration: Values

This section details the configurable parameters for different aspects of the Grant API, including authorization servers, client servers, and client applications.

### Authorization Server Configuration

- **`request_url`** (string) - The URL for requesting an access token.
- **`authorize_url`** (string) - The URL for authorizing the application.
- **`access_url`** (string) - The URL for accessing protected resources.
- **`oauth`** (integer) - Specifies the OAuth version.
- **`scope_delimiter`** (string) - The delimiter used for scopes.
- **`token_endpoint_auth_method`** (string) - The authentication method for the token endpoint.
- **`token_endpoint_auth_signing_alg`** (string) - The signing algorithm for token endpoint authentication.

### Client Server Configuration

- **`origin`** (string) - The origin URL of the client server.
- **`prefix`** (string) - The prefix for Grant routes.
- **`state`** (boolean) - Whether to use state parameter.
- **`nonce`** (boolean) - Whether to use nonce parameter.
- **`pkce`** (boolean) - Whether to use PKCE.
- **`response`** (array of strings) - The types of responses to request.
- **`transport`** (string) - The transport mechanism for callbacks.
- **`callback`** (string) - The callback URL for the provider.
- **`overrides`** (object) - Provider-specific overrides.
- **`dynamic`** (array of strings) - Dynamic configuration parameters.

### Client App Configuration

- **`key`**, **`client_id`**, **`consumer_key`** (string) - The client ID or consumer key.
- **`secret`**, **`client_secret`**, **`consumer_secret`** (string) - The client secret or consumer secret.
- **`scope`** (array of strings) - The requested scopes.
- **`custom_params`** (object) - Custom parameters for the authorization request.
- **`subdomain`** (string) - The subdomain for the provider.
- **`public_key`** (string) - The public key for JWT signing.
- **`private_key`** (string) - The private key for JWT signing.
- **`redirect_uri`** (string) - The redirect URI for the OAuth app.

### Grant Configuration

- **`name`** (string) - The name of the grant.
- **`[provider]`** (boolean) - Indicates if the provider is enabled.
- **`profile_url`** (string) - The URL to fetch user profile information.
```

--------------------------------

### Mounting Grant with Path Prefix (JavaScript)

Source: https://github.com/simov/grant/blob/master/README.md

Shows how to mount the Grant middleware under a specific path prefix (e.g., '/oauth') for Express, Koa, and Hapi applications, adjusting callback routes accordingly.

```javascript
// Express
app.use('/oauth', grant(config))
```

```javascript
// Koa - using koa-mount
app.use(mount('/oauth', grant(config)))
```

```javascript
// Hapi
server.register([{routes: {prefix: '/oauth'}, plugin: grant(config)}])
```

```javascript
// Fastify
server.register(grant(config), {prefix: '/oauth'})
```

--------------------------------

### Configuration: Scopes

Source: https://github.com/simov/grant/blob/master/README.md

Explains the six levels of configuration precedence Grant uses.

```APIDOC
## Configuration: Scopes

Grant integrates configuration from six distinct sources, with a defined order of precedence:

1.  **`oauth.json`**: Built-in configuration file.
2.  **`defaults`**: User-defined default configurations.
3.  **Provider Configuration**: Options defined directly for each provider.
4.  **`overrides`**: Static overrides for providers.
5.  **Dynamic State Override**: Runtime configuration overrides via HTTP framework state.
6.  **Dynamic HTTP Override**: Runtime configuration overrides via dynamic HTTP requests.
```

--------------------------------

### Dynamic Configuration for All Providers (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Enables dynamic configuration overrides for any provider, including those not explicitly pre-configured, by setting 'dynamic: true' under 'defaults'.

```json
{
  "defaults": {
    "dynamic": true
  }
}
```

--------------------------------

### Enable PKCE for OAuth Providers

Source: https://github.com/simov/grant/blob/master/README.md

PKCE (Proof Key for Code Exchange) can be enabled globally or per provider to enhance security. Providers that do not support PKCE will ignore these parameters.

```json
{
  "google": {
    "pkce": true
  }
}
```

--------------------------------

### Dynamic OAuth Configuration for All Keys (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

This JSON configuration allows all configuration keys for a specific provider (e.g., 'github') to be overridden dynamically via HTTP requests.

```json
{
  "github": {
    "dynamic": true
  }
}
```

--------------------------------

### Path Prefix Configuration with Origin (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Configures both the 'origin' and 'prefix' for Grant, resulting in OAuth login URLs like 'http://localhost:3000/oauth/login/:provider' and corresponding callback URIs.

```json
{
  "defaults": {
    "origin": "http://localhost:3000",
    "prefix": "/oauth/login"
  }
}
```

--------------------------------

### Meta Configuration for Provider Documentation (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Adds arbitrary metadata to a provider's configuration, such as 'app' name, 'owner' email, and 'url' for managing the OAuth app. 'meta' is a reserved key.

```json
{
  "google": {
    "meta": {
      "app": "My Awesome OAuth App",
      "owner": "my_email@gmail.com",
      "url": "https://url/to/manage/oauth/app"
    }
  }
}
```

--------------------------------

### Enable JSON Modules for ES Modules

Source: https://github.com/simov/grant/blob/master/README.md

A command-line flag to enable experimental JSON module support when running Node.js applications with ES Modules.

```bash
node --experimental-json-modules app.mjs
```

--------------------------------

### Prefixing Callback Routes (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Optionally defines a specific path prefix for the callback routes of a particular provider, such as 'github', to customize the callback endpoint.

```json
{
  "github": {
    "callback": "/oauth/login/hello"
  }
}
```

--------------------------------

### Redirect URI Generation with Origin (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Illustrates how the 'origin' configuration combined with provider defaults is used to automatically generate the correct 'redirect_uri' for callbacks.

```json
{
  "defaults": {
    "origin": "https://mysite.com"
  },
  "google": {},
  "twitter": {}
}
```

--------------------------------

### Configurable Prefix for Grant Routes

Source: https://github.com/simov/grant/blob/master/README.md

Demonstrates how to configure a custom prefix for Grant's default routes, allowing for flexibility in API path management. This changes the base path for connect and callback routes.

```json
{
  "defaults": {
    "origin": "http://localhost:3000",
    "prefix": "/oauth"
  }
}
```

--------------------------------

### Connect: Redirect URI

Source: https://github.com/simov/grant/blob/master/README.md

Details the format and usage of the `redirect_uri` for OAuth applications.

```APIDOC
## Connect: Redirect URI

The `redirect_uri` for your OAuth application should adhere to the following format:

`[origin][prefix]/[provider]/callback`

- **`origin`**: Must match the `origin` configured in Grant.
- **`prefix`**: Must match the `prefix` configured in Grant.
- **`provider`**: The key identifying the provider in your Grant configuration.

### Example
`http://localhost:3000/connect/google/callback`

This `redirect_uri` is utilized internally by Grant. The response data is received either at the configured `callback` route or an absolute URL, depending on the `transport` method employed.
```

--------------------------------

### Import Grant in ES Modules with TypeScript

Source: https://github.com/simov/grant/blob/master/README.md

Demonstrates importing Grant, express, session, and config in an ES Module (.mjs) file for use with TypeScript. Sets up express, session, and Grant middleware.

```javascript
import express from 'express'
import session from 'express-session'
import grant from 'grant'
import config from './config.json'

express()
  .use(session({}))
  .use(grant.express(config))
```

--------------------------------

### Configure HTTP Client with Request Options

Source: https://github.com/simov/grant/blob/master/README.md

Configures the underlying HTTP client for Grant using the 'request' option, allowing for agent and timeout settings. Requires the 'grant' module.

```javascript
var grant = require('grant').express({
  config,
  request: {agent, timeout: 5000}
})
```

--------------------------------

### Access Grant Instance Configuration

Source: https://github.com/simov/grant/blob/master/README.md

Demonstrates how to access the internal configuration of a Grant instance using the `config` property. Changes made here affect the entire Grant instance and can be used to alter behavior at runtime.

```javascript
var grant = Grant(require('./config'))
console.log(grant.config)
```

--------------------------------

### Custom Scope Parameter Handling for Flickr, Freelancer, Optimizely

Source: https://github.com/simov/grant/blob/master/README.md

Flickr, Freelancer, and Optimizely use custom parameters for scopes (`perms`, `advanced_scopes`, `scopes` respectively). Grant allows using the standard `scope` option to abstract these differences.

```json
{
  "flickr": {
    "scope": ["write"]
  },
  "freelancer": {
    "scope": ["1", "2"]
  },
  "optimizely": {
    "scope": ["all"]
  }
}
```

--------------------------------

### Connect: Origin

Source: https://github.com/simov/grant/blob/master/README.md

Defines the `origin` parameter, specifying the client server's reachability.

```APIDOC
## Connect: Origin

The `origin` configuration specifies the base URL where your client server can be reached.

### Example
```json
{
  "defaults": {
    "origin": "http://localhost:3000"
  }
}
```

Login initiation occurs by navigating to the `/connect/:provider` route, where `:provider` is a key in your Grant configuration. You can also log in via a static override by navigating to `/connect/:provider/:override?`.
```

--------------------------------

### VisualStudio Client Secret Configuration

Source: https://github.com/simov/grant/blob/master/README.md

When configuring VisualStudio with Grant, ensure that the `secret` parameter is set to your Client Secret, not the App Secret.

```json
{
  "visualstudio": {
    "key": "APP_ID",
    "secret": "CLIENT_SECRET instead of APP_SECRET"
  }
}
```

--------------------------------

### Dynamic Shopify Subdomain Form (HTML)

Source: https://github.com/simov/grant/blob/master/README.md

An HTML form to capture the subdomain for the Shopify OAuth flow. This form submits the 'subdomain' value to the Grant connection route.

```html
<form action="/connect/shopify" method="POST" accept-charset="utf-8">
  <input type="text" name="subdomain" value="" />
  <button>Login</button>
</form>
```

--------------------------------

### Openstreetmap Provider Configuration

Source: https://github.com/simov/grant/blob/master/README.md

For Openstreetmap OAuth 2.0, use the `openstreetmap2` provider. This configuration includes enabling a state parameter and specifying requested scopes.

```json
{
  "openstreetmap2": {
    "state": true,
    "scope": [
      "openid",
      "read_prefs"
    ]
  }
}
```

--------------------------------

### Ebay Redirect URI Configuration

Source: https://github.com/simov/grant/blob/master/README.md

For Ebay, the `redirect_uri` in Grant's configuration must be set to the RuName generated by Ebay's OAuth app. This ensures proper callback handling.

```json
{
  "ebay": {
    "redirect_uri": "RUNAME"
  }
}
```

--------------------------------

### Explicit Redirect URI Configuration (JSON)

Source: https://github.com/simov/grant/blob/master/README.md

Shows how explicitly setting the 'redirect_uri' for providers overrides the URI generated by the 'origin' configuration.

```json
{
  "google": {
    "redirect_uri": "https://mysite.com/connect/google/callback"
  },
  "twitter": {
    "redirect_uri": "https://mysite.com/connect/twitter/callback"
  }
}
```

--------------------------------

### SurveyMonkey API Key Configuration

Source: https://github.com/simov/grant/blob/master/README.md

For SurveyMonkey, configure Grant by setting your Mashery user name as `key` and your application key as `api_key` within `custom_params`.

```json
{
  "surveymonkey": {
    "key": "MASHERY_USER_NAME",
    "secret": "CLIENT_SECRET",
    "custom_params": {"api_key": "CLIENT_ID"}
  }
}
```

--------------------------------

### Configure OpenID Connect for Authentication

Source: https://github.com/simov/grant/blob/master/README.md

Enables OpenID Connect for authentication by requiring the 'openid' scope and optionally generating a 'nonce' for security. It also notes that Grant does not verify the ID token signature by default but validates 'aud' and 'nonce' claims.

```json
{
  "google": {
    "scope": ["openid"],
    "nonce": true
  }
}
```

--------------------------------

### Configure Static Overrides for Provider Settings

Source: https://github.com/simov/grant/blob/master/README.md

Allows overriding specific provider configurations, such as scopes and callback URLs, for different endpoints. This enables granular control over authorization requests.

```json
{
  "github": {
    "key": "...", "secret": "...",
    "scope": ["public_repo"],
    "callback": "/hello",
    "overrides": {
      "notifications": {
        "key": "...", "secret": "...",
        "scope": ["notifications"]
      },
      "all": {
        "scope": ["repo", "gist", "user"],
        "callback": "/hey"
      }
    }
  }
}
```

--------------------------------

### Manual Redirect for Sandbox Feedly OAuth

Source: https://github.com/simov/grant/blob/master/README.md

JavaScript code to handle manual redirection for the Feedly OAuth flow in a development environment when the redirect_uri is overridden. It redirects to the Grant callback route with the authorization code.

```javascript
var qs = require('querystring')

app.get('/', (req, res) => {
  if (process.env.NODE_ENV === 'development' &&
      req.session.grant &&
      req.session.grant.provider === 'feedly' &&
      req.query.code
  ) {
    res.redirect(`/connect/${req.session.grant.provider}/callback?${qs.stringify(req.query)}`)
  }
})
```

--------------------------------

### Mastodon Subdomain Configuration

Source: https://github.com/simov/grant/blob/master/README.md

Mastodon requires the full domain to be embedded in OAuth URLs. Use the `subdomain` option in Grant to specify your Mastodon server's domain.

```json
{
  "mastodon": {
    "subdomain": "mastodon.cloud"
  }
}
```

--------------------------------

### OAuth 1.0a Callback Data Structure

Source: https://github.com/simov/grant/blob/master/README.md

Defines the structure of data returned after a successful OAuth 1.0a authorization, including access_token, access_secret, and raw response data.

```javascript
{
  access_token: '...',
  access_secret: '...',
  raw: {
    oauth_token: '...',
    oauth_token_secret: '...',
    some: 'other data'
  }
}
```

--------------------------------

### OAuth 2.0 Callback Data Structure

Source: https://github.com/simov/grant/blob/master/README.md

Defines the structure of data returned after a successful OAuth 2.0 authorization, including id_token, access_token, refresh_token, and raw response data.

```javascript
{
  id_token: '...',
  access_token: '...',
  refresh_token: '...',
  raw: {
    id_token: '...',
    access_token: '...',
    refresh_token: '...',
    some: 'other data'
  }
}
```

--------------------------------

### Override Sandbox Redirect URI for Feedly

Source: https://github.com/simov/grant/blob/master/README.md

JSON configuration to override the default redirect_uri for Feedly's OAuth sandbox app, setting it to 'http://localhost' to match provider limitations. This requires manual redirection handling.

```json
"feedly": {
  "redirect_uri": "http://localhost"
}
```

--------------------------------

### Configure Callback Transport as Querystring

Source: https://github.com/simov/grant/blob/master/README.md

Configures Grant to return OAuth response data encoded as a querystring in the callback URL. This is useful for OAuth proxies but may leak data.

```json
{
  "github": {
    "callback": "https://site.com/hello"
  }
}
```

--------------------------------

### Dynamically Set Grant State

Source: https://github.com/simov/grant/blob/master/README.md

Shows how to alter Grant's configuration for a specific request/response lifecycle using a state object. This is useful for passing sensitive data dynamically and overriding any configuration key.

```javascript
var state = {dynamic: {subdomain: 'usershop'}}
res.locals.grant = state // Express
ctx.state.grant = state // Koa
req.plugins.grant = state // Hapi
req.grant = state // Fastify
await grant(..., state) // Serverless Function
```

--------------------------------

### Limit Querystring Response Data

Source: https://github.com/simov/grant/blob/master/README.md

Configures the querystring transport to return only specific data, such as 'tokens', to avoid sending excessive data which can cause compatibility issues.

```json
{
  "defaults": {
    "response": ["tokens"]
  }
}
```

--------------------------------

### Configure Callback Transport using State

Source: https://github.com/simov/grant/blob/master/README.md

Configures Grant to use the request/response lifecycle 'state' to store OAuth response data. This method bypasses the need for a callback route.

```json
{
  "defaults": {
    "transport": "state"
  }
}
```

--------------------------------

### Twitter OAuth 1.0a and 2.0 Configuration

Source: https://github.com/simov/grant/blob/master/README.md

Twitter's OAuth 1.0a allows specifying custom scope parameters via `custom_params` or the `scope` option. For OAuth 2.0, use the `twitter2` provider with `state` and `pkce` enabled, along with specified scopes.

```json
{
  "twitter": {
    "custom_params": {"x_auth_access_type": "read"}
  }
}
{
  "twitter": {
    "scope": ["read"]
  }
}
{
  "twitter2": {
    "state": true,
    "pkce": true,
    "scope": [
      "users.read",
      "tweet.read"
    ]
  }
}
```

--------------------------------

### Limit Session Response Data

Source: https://github.com/simov/grant/blob/master/README.md

Configures the session transport to return only specified data like 'tokens' to prevent potential HTTP request rejections due to large header sizes when the session store encodes the entire session in a cookie.

```json
{
  "google": {
    "response": ["tokens"]
  }
}
```

--------------------------------

### Callback Error Data Structure

Source: https://github.com/simov/grant/blob/master/README.md

Represents the structure of data returned in case of an error during the OAuth callback process.

```javascript
{
  error: {
    some: 'error data'
  }
}
```

--------------------------------

### Include Profile in Response Data

Source: https://github.com/simov/grant/blob/master/README.md

Requests user profile information during the OAuth flow by setting the response to include 'profile'. This adds a 'profile' key to the response data, containing user-specific information.

```json
{
  "google": {
    "response": ["tokens", "profile"]
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.