Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

The token endpoint answers with unsupported_grant_type

Errorunsupported_grant_type

Short answer

unsupported_grant_type means the authorization server did not accept the grant type in your token request. Send a POST to the token endpoint with a body of type application/x-www-form-urlencoded and a grant_type field spelled exactly as the flow needs, such as password. JSON bodies, form-data bodies and GET requests are the usual mistakes.

  • Applies to OAuth 2.0 as defined in RFC 6749, curl 8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Send the request from a terminal so no client tool changes the headers or the body, and read the full response.

    curl -i -X POST https://example.com/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data-urlencode "grant_type=password" \
      --data-urlencode "username=user@example.com" \
      --data-urlencode "password=secret"
  2. 2Match what you see, then jump to its fix

    1. 1The same values work from curl with --data-urlencode but fail from Postman raw JSON or form-dataThe body is JSON or multipart form-data, not form-urlencodedFix
    2. 2error is unsupported_grant_type or invalid_request, and the body has no grant_type or a different spellinggrant_type is missing, misspelled or the wrong value for the flowFix
    3. 3The token URL works in a browser address bar but returns an error or 405The request uses GET or sends the values in the query stringFix

What does the error look like?

  • unsupported_grant_type
  • invalid_request

Cause 1 of 3

The body is JSON or multipart form-data, not form-urlencoded

1Check

Token requests carry their parameters in the request body as application/x-www-form-urlencoded. A raw JSON body or a form-data body is not that format, so the server finds no grant_type in it.

curl -i -X POST https://example.com/token -H "Content-Type: application/json" -d '{"grant_type":"password"}'

2Fix

In Postman choose Body, then x-www-form-urlencoded, and add the fields as key and value rows. In code, send a form body and set the Content-Type header to application/x-www-form-urlencoded.

curl -i -X POST https://example.com/token \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=user@example.com" \
  --data-urlencode "password=secret"

3Verify

The response is a JSON object with access_token, not an error object.

curl -s -X POST https://example.com/token --data-urlencode "grant_type=password" --data-urlencode "username=user@example.com" --data-urlencode "password=secret"

Confirmed by datatracker.ietf.org

Did this fix it?

Cause 2 of 3

grant_type is missing, misspelled or the wrong value for the flow

1Check

For the resource owner password flow the value must be exactly password, with username and password fields next to it. RFC 6749 defines unsupported_grant_type as a grant type the server does not support, and invalid_request as a request with a missing parameter or a malformed one.

curl -i -X POST https://example.com/token --data-urlencode "grant_type=Password"

2Fix

Use the exact value the flow defines and include every required field. If the server never enabled that flow, use the flow it does support instead of retrying the same request.

curl -i -X POST https://example.com/token \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=user@example.com" \
  --data-urlencode "password=secret"

3Verify

The error no longer says unsupported_grant_type.

curl -s -X POST https://example.com/token --data-urlencode "grant_type=password" --data-urlencode "username=user@example.com" --data-urlencode "password=secret"

Confirmed by datatracker.ietf.org

Did this fix it?

Cause 3 of 3

The request uses GET or sends the values in the query string

1Check

RFC 6749 says the client must use the HTTP POST method for access token requests. A GET with parameters in the URL does not follow it.

curl -i "https://example.com/token?grant_type=password"

2Fix

Switch the method to POST and move every parameter into the request body.

curl -i -X POST https://example.com/token \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=user@example.com" \
  --data-urlencode "password=secret"

3Verify

The server now returns a token response for valid credentials.

curl -s -o /dev/null -w "%{http_code}\n" -X POST https://example.com/token --data-urlencode "grant_type=password" --data-urlencode "username=user@example.com" --data-urlencode "password=secret"

Confirmed by datatracker.ietf.org

Did this fix it?

How do I stop it coming back?

  • Keep one saved token request in your API client with the Body type set to x-www-form-urlencoded.
  • Send token requests over HTTPS only, because they carry credentials.
  • Prefer an authorization code flow with PKCE for new apps, because the password flow hands user credentials to the client.

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.