Authentication

The MGX Enterprise API uses OAuth2. Read-only data (inventory, market) can use the client-credentials flow; anything that acts as a user — placing bids, reading your trades — uses the authorization-code flow ("Login with MGX") so the token is bound to a specific MGX team.

Bearer tokens

Every request carries your access token in the Authorization header:

curl https://api.mygrainexchange.com/v1/inventory \
  -H "Authorization: Bearer {token}"

Keep your token and client secret safe. If you suspect the secret is compromised, rotate it in your MGX dashboard — click your name in the top-right corner and choose Developers.

Scopes

Request only the scopes your integration needs. User-context scopes require Login with MGX.

Scope	Grants	Restricted
`inventory.read`	Browse and filter anonymized inventory
`market.read`	Read market commodities, prices, and price history
`bids.read`	Read your team's bids
`bids.write`	Place bids on behalf of your team
`trades.read`	Read your team's trades
`teams.read`	Read the teams you belong to
`cashbids.read`	Read your cash bids and offers
`cashbids.write`	Create and update your cash bids
`listings.read`	Read your own inventory listings and the bids on them	✓
`listings.write`	Submit, update, and archive your inventory listings	✓
`farms.read`	See your farm names and locations	✓
`farms.write`	Create and edit your farms	✓
`analysis.read`	Read grain sample analysis offerings and graded results	✓
`analysis.write`	Request grain sample analysis on inventory you own or manage	✓
`locations.read`	Read your elevator delivery locations
`webhooks.read`	Read your webhook subscriptions
`webhooks.write`	Manage your webhook subscriptions
`openid` `profile` `email`	OpenID Connect sign-in claims for Login with MGX

Restricted scopes unlock the seller inventory-import surface and are not self-service. They are granted by MGX to approved partner clients — contact us if your integration needs them.

To act on behalf of a user and team, send them through the authorization-code flow with PKCE:

GET https://api.mygrainexchange.com/oauth/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={your_callback}
  &scope=openid profile email bids.write
  &state={random}
  &code_challenge={pkce_challenge}
  &code_challenge_method=S256

The user signs in, selects which team the integration may act as, and approves. You receive a code at your callback, which you exchange for tokens:

curl https://api.mygrainexchange.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id={client_id} \
  -d client_secret={client_secret} \
  -d redirect_uri={your_callback} \
  -d code_verifier={pkce_verifier} \
  -d code={code}

The selected team is bound to the issued token — every bid placed with it acts as that team. Call /oauth/userinfo for the identity claims (sub, email, name, mgx_team_id, mgx_roles).

Client credentials (read-only)

For server-to-server read access where no user is involved:

curl https://api.mygrainexchange.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id={client_id} \
  -d client_secret={client_secret} \
  -d scope="inventory.read market.read"

Authentication

Bearer tokens

Scopes

Login with MGX (authorization code)

Client credentials (read-only)