OAuth responses

Request through URL (implicit flow)

When requesting an access token during an implicit flow, the application directs the user to the following URL:

Authorization_Endpoint_URL?response_type=token&
redirect_uri=Redirect_URI&scope=Scope&
client_id=Client_ID

where:

• Authorization_Endpoint_URL is the authorization endpoint of the API from which the application is requesting access.
• Redirect_URI is the redirect URI of the application.
• Scope is the scope of access the application is requesting.
• Client_ID is the client ID of the application.

Requesting a token can result in the following responses:

• If authorization is granted by the user and the request is successful, the user is redirected to the following URL:

  Redirect_URI#access_token=Access_Token&expires_in=3600&
  scope=Scope&token_type=bearer

  where Access_Token is the access token requested.

• If authorization is not granted by the user and the request would otherwise be successful, the user is redirected to the following URL:

  Redirect_URI#error=access_denied

• If the Redirect_URI is incorrect, the user is not redirected and is presented with the following message:

  OAuth Error
  An error occurred while processing the OAuth request.
  Error:invalid_request
  Error Description:invalid redirect_uri

• If the Redirect_URI is incorrect in the request and present in the application, or if it is missing in the application, the user is presented with the following message:

  { "error":"unknown" }

  In this situation, the flow can still proceed if no other errors occur.

• If the Scope is incorrect or missing, the user is redirected to the following URL:

  Redirect_URI#error=invalid_scope

• If the Client_ID is incorrect, the user is presented with the following message:

  { "error":"invalid_client", "error_description":"client_id unauthorized" }

Request through URL (access code flow)

When requesting an access token during an access flow, the application directs the user to the following URL:

Authorization_Endpoint_URL?response_type=code&
redirect_uri=Redirect_URI&scope=Scope&
client_id=Client_ID

where:

• Authorization_Endpoint_URL is the authorization endpoint of the API from which the application is requesting access.
• Redirect_URI is the redirect URI of the application.
• Scope is the scope of access the application is requesting.
• Client_ID is the client ID of the application.

Requesting an authorization code can result in the following responses:

• If authorization is granted by the user and the request is successful, the user is redirected to the following URL:

  Redirect_URI?code=Authorization_Code

  where Authorization_Code is the requested code.

• If the Redirect_URI is incorrect, the user is not redirected and is presented with the following message:

  OAuth Error
  An error occurred while processing the OAuth request.
  Error:invalid_request
  Error Description:invalid redirect_uri

• If the Scope is incorrect or missing, the user is redirected to the following URL:

  Redirect_URI#error=invalid_scope

• If the Redirect_URI is incorrect in the request and present in the application, or if it is missing in the application, the user is presented with the following message:

  { "error":"unknown" }

  In this situation, the flow can still proceed if no other errors occur.

• If the Client_ID is incorrect, the user is presented with the following message:

  { "error":"invalid_client", "error_description":"client_id unauthorized" }

• If authorization is not granted by the user and the request would otherwise be successful, the user is redirected to the following URL:

  Redirect_URI#error=access_denied

Request for access token (incorrect grant type)

If an incorrect grant type is provided, API Connect for IBM Cloud cannot identify the grant type, and therefore the flow, that was intended to be used.

When requesting an access token during an access code, application, or password flow, the application makes a POST call to the following URL:

Token_Endpoint_URL

Part of the request header sent by the application includes the following information:

grant_type=Grant_Type

where Grant_Type corresponds to the OAuth flow in use and can take the following values:

• authorization_code
• client_credentials
• password

If Grant_Type is not one of the previous options, the following response is returned:

400 Processed
{ "error":"invalid_request" }

Request for access token (public access code flow)

When requesting an access token during a public access code flow, the application makes a POST call to the following URL:

Token_Endpoint_URL

The application includes the following information in its request header:

grant_type=authorization_code
code=Authorization_Code
redirect_uri=Redirect_URI
client_id=Client_ID

where

• Authorization_Code is the code obtained when the user granted authorization.
• Redirect_URI is the redirect URI of the application.
• Client_ID is the client ID of the application.

Requesting an access token can result in the following responses:

• If the request is successful and refresh tokens are not enabled, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/Scope}

  Where Access_Token is the requested access token and Scope is the scope of access that is allowed by the token.

• If the request is successful and refresh tokens are enabled, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/scope,"refresh_token":Refresh_Token}

  where Refresh_Token is a token that can be used to obtain another access token once the original has expired.

• If Authorization_Code is invalid, the following response is returned:

  400 Processed
  { "error":"invalid_grant" }

• If Redirect_URI is missing, the following response is returned:

  400 Processed
  { "error":"invalid_request" }

  Note:

  When an application requests an access token (after obtaining an authorization code) during a public or confidential access code flow (grant_type=authorization code), and the request header is missing the Redirect URI, the method by which the application was created makes a difference in the API Connect for IBM Cloud OAuth response behavior.

  An application can be created through the Developer Portal (see Applications in the Developer Portal), or created in an API Manager community (see Developing your APIs and applications):

  • If the application is created through the Developer Portal, there is no default Redirect URI. In this case, if the application does not supply a Redirect URI during an authorization request, the response is: 400 Processed { "error":"invalid_request" }.
  • If the application is created through the API Manager community, API Connect for IBM Cloud automatically provides a default Redirect URI of https://localhost. In this case, if the application does not supply a Redirect URI, the default URI is used, and the response code is 200 OK. The default URI also applies to authorization and token endpoint calls.
• If Redirect_URI is incorrect, the following response is returned:

  400 Processed
  { "error":"invalid_grant" }

• If Client_ID is incorrect or missing, the following response is returned:

  401 Unauthorized
  { "error":"invalid_client", "error_description":"client_id unauthorized" }

Request for access token (confidential access code flow)

When requesting an access token during a confidential access code flow, the application makes a POST call to the following URL:

Token_Endpoint_URL

The application includes Client_ID as a user name and Client_Secret as a password. The application also includes the following information in its header:

grant_type=authorization_code
code=Authorization_Code
redirect_uri=Redirect_URI

where

• Authorization_Code is the code obtained when the user granted authorization.
• Redirect_URI is the redirect URI of the application.
• Client_ID is the client ID of the application and is used as a user name.
• Client_Secret is the client secret of the application and is used as a password.

Requesting an access token can result in the following responses:

• If the request is successful and refresh tokens are not enabled, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/Scope}

  Where Access_Token is the requested access token and Scope is the scope of access that is allowed by the token.

• If the request is successful and refresh tokens are enabled, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/scope,"refresh_token":Refresh_Token}

  where Refresh_Token is a token that can be used to obtain another access token once the original has expired.

• If Authorization_Code is invalid, the following response is returned:

  400 Processed
  { "error":"invalid_grant" }

• If Authorization_Code is missing, the following response is returned:

  400 Processed
  { "error":"invalid_request" }

• If Redirect_URI is missing, the following response is returned:

  400 Processed
  { "error":"invalid_request" }

  For more information on the response for a missing Redirect_URI, see the Note in Request for access token (public access code flow).

• If Redirect_URI is incorrect, the following response is returned:

  400 Processed
  { "error":"invalid_grant" }

• If Client_ID or Client_Secret is incorrect or missing, the following response is returned:

  401 Unauthorized
  { "error":"invalid_client", "error_description":"client_id unauthorized" }

Request for an access token (application flow)

When requesting an access token during an application flow, the application makes a POST call to the following URL:

Token_Endpoint_URL

The application uses Client_ID as a user name and Client_Secret as a password. The application also includes the following information in its request header:

grant_type=client_credentials
scope=Scope

where

• Client_ID is the client ID of the application.
• Client_Secret is the client secret of the application.
• Scope is the scope of access requested.

Requesting an access token can result in the following responses:

• If the request is successful, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/Scope}

  Where Access_Token is the requested access token and Scope is the scope of access that is allowed by the token.

• If Client_ID or Client_Secret is incorrect or missing, the following response is returned:

  401 Unauthorized
  { "error":"invalid_client", "error_description":"client_id unauthorized" }

• If Scope is incorrect or missing, the following response is returned:

  401 Processed
  { "error":"invalid_scope" }

Request for an access token (public password flow)

When requesting an access token during a public password flow, the application makes a POST call to the following URL:

Token_Endpoint_URL

The application includes the following information in its request header:

grant_type=password
client_id=Client_ID
username=User_Name
password=Password
scope=Scope

where

• Client_ID is the client ID of the application.
• User_Name is the user name of the user whose credentials the application is using.
• Password is the password of the user whose credentials the application is using.
• Scope is the scope of access requested.

Requesting an access token can result in the following responses:

• If the request is successful and refresh tokens are not enabled, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/Scope}

  Where Access_Token is the requested access token and Scope is the scope of access that is allowed by the token.

• If the request is successful and refresh tokens are enabled, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/scope,"refresh_token":Refresh_Token}

  where Refresh_Token is a token that can be used to obtain another access token once the original has expired.

• If Client_ID or Client_Secret is incorrect or missing, the following response is returned:

  401 Unauthorized
  { "error":"invalid_client", "error_description":"client_id unauthorized" }

• If Scope is incorrect or missing, the following response is returned:

  401 Processed
  { "error":"invalid_scope" }

• If Password or User_Name is missing, the following response is returned:

  400 Processed
  { "error":"invalid_request" }

• If Password or User_Name is incorrect, the following response is returned:

  401 Unauthorized
  { "error":"invalid_grant" }

Request for an access token (confidential password flow)

When requesting an access token during a confidential password flow, the application makes a POST call to the following URL:

Token_Endpoint_URL

The application uses Client_ID as a user name and Client_Secret as a password. The application also includes the following information in its request header:

grant_type=password
username=User_Name
password=Password
scope=Scope

where

• Client_ID is the client ID of the application.
• Client_Secret is the client secret of the application.
• User_Name is the user name of the user whose credentials the application is using.
• Password is the password of the user whose credentials the application is using.
• Scope is the scope of access requested.

Requesting an access token can result in the following responses:

• If the request is successful, the following response is returned:

  200 OK
  {"token_type":"bearer","access_token":"Access_Token",
  "expires_in":3600,"scope":"/Scope}

  Where Access_Token is the requested access token and Scope is the scope of access that is allowed by the token.

• If Client_ID or Client_Secret is incorrect or missing, the following response is returned:

  401 Unauthorized
  { "error":"invalid_client", "error_description":"client_id unauthorized" }

• If Scope is incorrect or missing, the following response is returned:

  401 Processed
  { "error":"invalid_scope" }

• If Password or User_Name is missing, the following response is returned:

  400 Processed
  { "error":"invalid_request" }

• If Password or User_Name is incorrect, the following response is returned:

  401 Unauthorized
  { "error":"invalid_grant" }