This section outlines how to authenticate with the MidwayPlus Web API as a developer and generate a bearer authentication token to interact with accounts that have installed your app. There are two primary methods:

1. Developer-Driven Token Generation: Authenticate with your developer credentials, then generate a token using an app installation ID.
2. User Redirect Authentication: Redirect a logged-in user to an authentication endpoint to obtain a token directly via a redirect URL.

Both methods result in a bearer authentication token that is suitable to share with the client (e.g., a web browser) because it has a limited lifespan (expires after a set duration) and is restricted to the permissions tied to the specific app installation.

The developer-driven flow involves authenticating with your developer credentials, obtaining an app installation ID, and generating a limited-scope token for API operations.

1. Authenticate with Developer Credentials

Authenticate using your developer credentials to establish your identity as an authorized app developer.

Endpoint: POST /v1/Auth

Request:

curl -X POST https://api.midwayplus.com/v1/Auth \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "password": "your-password"
  }'

Response:

{
  "token": "developer-access-token"
}

The token returned here is your developer token, which you’ll use to generate app-specific tokens. This token should NOT be shared with client applications (e.g. web browsers), users of your app, or anyone.

2. Obtain an App Installation ID

Each installation of your app by a user is assigned a unique installationId. Retrieve a list of installations if you don’t already know the installationId.

Endpoint: GET /v1/Developer/Installations

Request:

curl -X GET https://api.midwayplus.com/v1/Developer/Installations \
  -H "Authorization: Bearer developer-access-token"

Response:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "appId": "string",
    "appName": "string",
    "partyType": "None",
    "partyId": 0,
    "partyName": "string",
    "installDate": "2025-03-21T17:28:48.698Z",
    "purchaseOptionId": "string",
    "installedVersion": "string",
    "userSettings": {
      "setting1": "string",
      "setting2": 500
    },
    "adminSettings": {
      "test": "string"
    }
  }
]

Select the id for the app installation/account you want to interact with.

3. Generate a Bearer Authentication Token

Generate a bearer token scoped to a specific app installation using the installation_id.

Endpoint: POST /v1/Developer/Token

Request:

curl -X POST https://api.midwayplus.com/v1/Developer/Token \
  -H "Authorization: Bearer developer-access-token" \
  -H "Content-Type: application/json" \
  -d '{
    "installationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Response:

{
  "token": "app-installation-specific-bearer-token"
}

4. Use the Bearer Token for API Operations

Use the bearer token in the Authorization header to perform API requests.

Example Endpoint: GET /api/v1/user/profile

Request:

curl -X GET https://api.midwayplus.com/v1/Products \
  -H "Authorization: Bearer app-installation-specific-bearer-token"

Response:

[
  {
    "id": 0,
    "brand": "string",
    "partNumber": "string",
    "inStock": 0,
    "shortDescription": "string",
    "msrp": 0,
    "mapPrice": 0,
    "upc": "string"
  }
]

General Use Case

For scenarios where a user is already logged into MidwayPlus and has installed your app, you can redirect them to an authentication endpoint. If your app is properly configured with a redirect URL (specified as AuthReturnUrl in your app settings) and the user has the app installed, the platform will redirect them back to your URL with a bearer token in the query parameters.

1. Redirect the User to the Authentication Endpoint

Direct the user to the following endpoint, including your app’s client_id as a query parameter.

Endpoint: GET /Apps/Authenticate/{your-app-id}

Request: https://app.midwayplus.com/Apps/Authenticate/{your-app-id}

- If the user is not logged into MidwayPlus, they will be prompted to log in.
- The app Id must match an app they have installed.

If successful, the platform authenticates the user, verifies the app installation, and redirects them to the AuthReturnUrl configured for your app.

2. Handle the Redirect and Extract the Token

The user will be redirected to your specified AuthReturnUrl with the bearer token included in the query parameters.

Redirect URL Example:

https://your-app.com/auth/callback?token=app-installation-specific-bearer-token

Query Parameters:

• token: The bearer token for API operations.

Your app should parse these parameters from the URL and use the token for subsequent API requests.

3. Use the Bearer Token for API Operations

Use the extracted token in the Authorization header, as described in the developer-driven flow.

Example:

curl -X GET https://api.midwayplus.com/v1/Products \
  -H "Authorization: Bearer app-installation-specific-bearer-token"

Notes

• Token Expiration: Bearer tokens from both methods expire after a set period. Regenerate a new token as needed.
• Security: Tokens are suitable to share with clients due to their limited scope and lifespan.
• Redirect Configuration: Ensure your app’s AuthReturnUrl is set in the App's settings to use the redirect method.
• Error Handling:
  • Developer-driven: Invalid installationId or expired developer token returns 401 Unauthorized or 403 Forbidden.
  • Redirect: If the user has not installed the app or the AuthReturnUrl is invalid, the redirect will fail, and an error page may be shown instead.