Manage Allowed Grant Types

A grant is a standard methodology by which a client contacts a server in order to obtain tokens and be granted access to resources. For example, with the authorization_code grant a user is authenticated and, in turn, the authorization endpoint sends the client an authorization code. That authorization code is then exchanged at the token endpoint for an access token, a refresh token, and an identity token.

By comparison, with the implicit grant the user is authenticated and then issued an access token by the authorization endpoint itself: the client never has to visit the token endpoint. 

Although Hosted Login supports a number of grant types, the actual grant types that can be included in an authorization request are dictated by a token policy’s allowedGrantTypes property; clients can only use the grant types included in that property. However, even though allowedGrantTypes is a token policy property, the allowed response types can’t be managed (or even viewed) by using the /tokenPolicies/{tokenPolicyId}endpoint. Instead, anyone who wants to work with response types must employ the /tokenPolicies/{tokenPolicyId}/allowedGrantType endpoint discussed below.

This endpoint supports the following methods:



GET


Description

Returns information about the grant types defined in the specified token policy. For example, the following token policy allows the use of the authorization_code and refresh_token grants:

[
    "authorization_code",
    "refresh_token"
]

Hosted Login supports the following grant types:

  • authorization_code. After authentication, a user is issued an authorization code. This code can be exchanged at the token endpoint for an access token, a refresh token, and an identity token.
  • implicit. Following a successful authentication, the authorization endpoint issues the client an access token and/or an identity token. The client never needs to visit the token endpoint.
  • refresh_token. Provides a way to exchange a refresh token for a new access token.
  • client_credentials. The client requests an access token for itself rather than requesting a token for a specific user. In Hosted Login, the client_credentials grant is typically used to obtain a configuration access token that can then be employed to call the OpenID Connect Configuration APIs.

URI Parameters

URI parameters that must be included in the request are listed in the following table:

Parameter

Type

Required

Description

{customerId}

String

Yes

Unique identifier of the organization associated with the token policy.

{tokenPolicyId}

String

Yes

Unique identifier for the token policy.


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must employ a configuration client (using the client ID as the username and the client secret as the password) to access the /{customerId}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. For example, if you get back the access token Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB then your Authorization header will look like this when using Curl:

-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.


Sample Request (curl)

The following command returns the allowed grant types found in token policy 5a1e3d0e-7a57-48ce-aa9c-b303345f5747:

curl -X GET \
'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/tokenPolicies/5a1e3d0e-7a57-48ce-aa9c-b303345f5747/allowedGrantTypes' \
  -H 'Authorization: Bearer dgqJbjCmon__P9OXLz5ulJtpS-jupleB-MBejblVMZHS8Nc-EeMSl91_b76WhtdA' 


Responses

200 OK

If your API call succeeds, you’ll get back a collection of the token policy's allowed grant types.

[
    "authorization_code",
    "refresh_token"
]


Error Response Codes

The following table includes information about some of the other response codes that you might encounter when calling this endpoint.

Response Code

Description

403

Forbidden. Typically occurs when you make a call using an invalid configuration token. This is usually because the token has expired (configuration tokens have a maximum lifetime of 1 hour). However, it’s also possible that the token wasn’t issued a scope capable of accessing push claim information. See the article API Security for Configuration for more information.

404

Not found. The specified token policy could not be found. This generally occurs because you referenced an invalid policy ID or customer ID when making your API call.




PUT

Back to top


Description

The PUT method enables you to specify the grant types supported by a given token policy; those policies can support any combination of the following:

  • authorization_code. After authentication, a user is issued an authorization code. This code can be exchanged at the token endpoint for an access token, a refresh token, and an identity token.
  • implicit. Following a successful authentication, the authorization endpoint issues the client an access token and/or an identity token. The client never needs to visit the token endpoint.
  • refresh_token. Provides a way to exchange a refresh token for a new access token.
  • client_credentials. The client requests an access token for itself rather than requesting a token for a specific user. In Hosted Login, the client_credentials grant is typically used to obtain a configuration access token that can then be employed to call the OpenID Connect Configuration APIs.

When updating the allowed grant types, your API call must specify all the desired types: that’s because the grant types included in the body parameter replace the current set of grant types. For example, suppose your token policy currently contains these two grant types:

  • authorization_code
  • refresh_token

Because you want to add implicit to the set of allowed response types, you use a body parameter that looks like this:

[
    "implicit"
]

After you make your API call, your token policy will contain the following set of grant types:

  • implicit

That’s because your previous set of allowed types (authorization_code and refresh_token) have been replaced by the new set (implicit) specified in the API call. To add implicit to the set of allowed grant types your body parameter must include your existing grant types as well as any new grant types being added to the token policy:

[
    "authorization_code",
    "refresh_token ",
    "implicit"
]

In addition to that, be sure you format your request as an array (that is, enclose your list of grant types within square brackets). For example, suppose your body parameter looks like this:

"implicit"

In that case, your API call will fail with the following error:

{
    "errors": "allowedGrantTypes must be a list of strings"
}


URI Parameters

URI parameters that must be included in the request are listed in the following table:

Parameter

Type

Required

Description

{customerId}

string

Yes

Unique identifier of the organization associated with the token policy.

{tokenPolicyId}

string

Yes

Unique identifier for the token policy.


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must employ a configuration client (using the client ID as the username and the client secret as the password) to access the /{customerId}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. For example, if you get back the access token Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB then your Authorization header will look like this when using Curl:

-H 'Authorization: Bearer Ki712dpGq5GPQcsxMHY6ShHY7wU_iTs0o9dPx4TEzf5yLIvddjnDVBJxjPDucf5YVB'

In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.


Sample Request (curl)

The following command sets the allowed grant types (authorization_code, refresh_token, password) for token policy 5a1e3d0e-7a57-48ce-aa9c-b303345f5747:

curl -X GET \
'https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/config/tokenPolicies/5a1e3d0e-7a57-48ce-aa9c-b303345f5747/allowedGrantTypes' \
-H 'Authorization: Bearer dgqJbjCmon__P9OXLz5ulJtpS-jupleB-MBejblVMZHS8Nc-EeMSl91_b76WhtdA' \
-H 'Content-Type: application/json' \
--data-raw '[
    "authorization_code",
    "refresh_token",
    "implicit"
]'


Responses

200 OK

If your API call succeeds you’ll get back a collection containing all the allowed grant types for the token policy:

[
    "authorization_code",
    "refresh_token",
    "implicit"
]


Error Response Codes

The following table includes information about some of the other response codes that you might encounter when calling this endpoint.

Response Code

Description

400

Bad request. Typically occurs if you specify a grant type not supported by Hosted Login. For example, if you attempt to add an invalid grant type named bob you’ll receive the following error message:

{
    "errors": "allowedGrantTypes contains invalid values: bob"
}

A 400 response code is also generated if your body parameter is not formatted as a JSON array:

{
    "errors": "allowedGrantTypes must be a list of strings"
}

403

Forbidden. Typically occurs when you make a call using an invalid configuration token. This is usually because the token has expired (configuration tokens have a maximum lifetime of 1 hour). However, it’s also possible that the token wasn’t issued a scope capable of accessing grant type information. See the article API Security for Configuration for more information.

404

Not found. The specified token policy could not be found. This generally occurs because you referenced an invalid policy ID or customer ID when making your API call.