Rate this page

Password Grant Type

This is a special grant type made directly to the token endpoint using the end user’s username and password credentials. Because the authorization endpoint is not involved, the client is responsible for collecting these credentials from the end user, and special features of the authorization endpoint, such as consent capture and multi-factor authentication, are not used.

Token request

POST /oauth/token

The client uses HTTP basic authentication with its client ID and client secret to authenticate itself to the token endpoint and must specify a Content-Type of application/x-www-form-urlencoded. The following parameters are provided in the body of the request using form-urlencoding.

Parameter Required? Description
grant_type yes Value must be password.
username yes The username of a resource owner.
password yes The password of a resource owner. If changing a resource owner’s password, this specifies the current password.
scope no A space-delimited set of scope names. If omitted, the client’s default scopes are used.

By default, scopes requested using this grant type must be of type Generic or Authenticated Identity. By default, scopes of type Resource will only be granted for users with privileged entitlements.

If a scope is configured to require consent, then it will only be granted if the user has previously provided consent for the scope. The user cannot be prompted to provide consent when using this grant type, because the authorization endpoint is not used.

Example request:

POST /oauth/token HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic dGVzdDE6cGFzc3dvcmRwYXNzd29yZHBhc3N3b3JkcGFzc3dvcmQ=
Connection: keep-alive
Content-Length: 74
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:443

grant_type=password&username=user.5&password=password&scope=email_addresses+name

Token response

If the token request succeeds, the server will respond with a 200 response code.

Field Type Provided? Description
access_token string always The access token.
token_type string always The access token type. The value is always Bearer.
refresh_token string The refresh token, if one was requested.
expires_in number always A value in seconds indicating the lifetime of the access token.
scope string always A space-delimited set of the scopes actually granted. This may be a subset of the requested scopes.
password_expiring boolean Returned if the user store has determined that the user’s password will expire soon. This nonstandard field is proprietary to the Ping Identity Data Governance Broker.

Example response:

HTTP/1.1 200 OK
Content-Length: 230
Content-Type: application/json
Date: Mon, 18 Apr 2016 23:05:09 GMT
Pragma: no-cache
Cache-Control: no-store

{
    "access_token": "eyJraWQiOiJBY2Nlc3MgVG9rZW4gU2lnbmluZyBLZXkgUGFpciIsImFsZyI6IlJTNTEyIn0.eyJzdWIiOiJVc2Vyc1wvOTkyM2RiYjgtZTdjNi00NjlmLWI3ZGItYWY3OTMxNzc0MDQ0Iiwic2NvcGUiOiJlbWFpbF9hZGRyZXNzZXMgbmFtZSIsImV4cCI6MTQ3NTMzODIyNywiaWF0IjoxNDc0OTA2MjI3LCJjbGllbnRfaWQiOiJ0ZXN0MSIsImp0aSI6ImEuZFF4cTBBIn0.maS5H_1NGQaIRX9OpT0nk4pLL2xrbBcFIBcP_7G9ojnfVbAiMYHNLpcE89-djjAwfZE4gjOWO4WB8b7GhHF1ZVnsyrPki2cMiCJuJP2c_j2elLYnzudkzaU4OcdvGpOfNSmS7u4vYv3PMi3RQo3aEXjfJBjxRrMfjsr0Mhbok7iKs-jw34zOumBI5zbFjHv9qk8Idx3WfYdEWm1PqsnP8I3eT1uY19n2YDyHkTmUsPds7dKUJp9u0Ckktnq1q2bGdBOpmT6zsf5JS590E3RwZCCepo8HtjGzJTdKfY4rfzvtLRy10neUKPr87X7NvE6XjZ3Hvh_IzvFK_jk4HeJLqw",
    "expires_in": 43200,
    "scope": "email_addresses name",
    "token_type": "Bearer"
}