Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

Box returns 'Invalid grant_type parameter or parameter missing'

ErrorInvalid grant_type parameter or parameter missing

Short answer

Box sends this invalid_request error when the token call cannot be read as a valid grant. Post to https://api.box.com/oauth2/token, not app.box.com or www.box.com. Send form-encoded grant_type with one of the documented values plus that grant's fields. Also check your app uses the matching auth method.

  • Applies to Box OAuth 2.0 API
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Send the token request by hand to the API host. The response body names the error and its description.

    curl -i -X POST https://api.box.com/oauth2/token \
      -d grant_type=authorization_code \
      -d code="$CODE" \
      -d client_id="$BOX_CLIENT_ID" \
      -d client_secret="$BOX_CLIENT_SECRET"
  2. 2Match what you see, then jump to its fix

    1. 1Invalid grant_type parameter or parameter missing, from a URL that is not api.box.comThe request goes to the wrong Box domainFix
    2. 2the same message and an HTTP 400grant_type is missing, misspelled or sent as JSONFix
    3. 3The grant type is unauthorized for this client_idThe grant type does not match how the app is configuredFix

What does the error look like?

  • Invalid grant_type parameter or parameter missing
  • error: invalid_request
  • The grant type is unauthorized for this client_id

Cause 1 of 3

The request goes to the wrong Box domain

1Check

Box lists token requests sent to app.box.com or www.box.com as a cause of this message.

grep -rn "box.com/oauth2/token" .

2Fix

Use https://api.box.com/oauth2/token for every token and refresh call. (app.box.com/api/oauth2/authorize is only the page where the user approves.)

POST https://api.box.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

3Verify

The response now returns a JSON access token or a different, more specific error.

curl -s -X POST https://api.box.com/oauth2/token -d grant_type=refresh_token -d refresh_token="$REFRESH" -d client_id="$BOX_CLIENT_ID" -d client_secret="$BOX_CLIENT_SECRET"

Confirmed by developer.box.com

Did this fix it?

Cause 2 of 3

grant_type is missing, misspelled or sent as JSON

1Check

The token endpoint takes application/x-www-form-urlencoded, and grant_type is the one required field. Allowed values are authorization_code, refresh_token, client_credentials, urn:ietf:params:oauth:grant-type:jwt-bearer and urn:ietf:params:oauth:grant-type:token-exchange.

# log the raw body your HTTP client sends and check it starts with grant_type=...

2Fix

Send form fields, not a JSON body. For the authorization code flow send grant_type=authorization_code with code, client_id and client_secret; for refresh send grant_type=refresh_token with refresh_token.

curl -X POST https://api.box.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH" \
  -d client_id="$BOX_CLIENT_ID" \
  -d client_secret="$BOX_CLIENT_SECRET"

3Verify

HTTP 200 with access_token, expires_in and token_type in the body.

# check the JSON response contains access_token

Confirmed by developer.box.com

Did this fix it?

Cause 3 of 3

The grant type does not match how the app is configured

1Check

Box documents this when the request type differs from the app's authentication method, for example a standard OAuth 2.0 request sent to an app set up for JWT. In the Developer Console, open the app's Configuration tab and read the Authentication Method.

# Developer Console > My Platform Apps > your app > Configuration

2Fix

Use the grant that matches the method: authorization_code or refresh_token for OAuth 2.0, the jwt-bearer grant with an assertion for JWT, client_credentials for Client Credentials Grant.

# JWT app: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
#          plus client_id, client_secret and assertion

3Verify

The token call returns an access_token.

# response status 200

Confirmed by developer.box.com

Did this fix it?

How do I stop it coming back?

  • Exchange the authorization code immediately; Box says it is valid for 30 seconds.
  • Keep client_id and client_secret in environment variables, not in the repo.
  • Log the Box error and error_description fields, not just the HTTP status.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.