Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

StartDeviceAuthorization

Initiates device authorization by requesting a pair of verification codes from the authorization service.

Request Syntax


POST /device_authorization HTTP/1.1
Content-type: application/json

{
   "clientId": "string",
   "clientSecret": "string",
   "startUrl": "string"
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

clientId

The unique identifier string for the client that is registered with IAM Identity Center. This value should come from the persisted result of the RegisterClient API operation.

Type: String

Required: Yes

clientSecret

A secret string that is generated for the client. This value should come from the persisted result of the RegisterClient API operation.

Type: String

Required: Yes

startUrl

The URL for the AWS access portal. For more information, see Using the AWS access portal in the IAM Identity Center User Guide.

Type: String

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "deviceCode": "string",
   "expiresIn": number,
   "interval": number,
   "userCode": "string",
   "verificationUri": "string",
   "verificationUriComplete": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

deviceCode

The short-lived code that is used by the device when polling for a session token.

Type: String

expiresIn

Indicates the number of seconds in which the verification code will become invalid.

Type: Integer

interval

Indicates the number of seconds the client must wait between attempts when polling for a session.

Type: Integer

userCode

A one-time user verification code. This is needed to authorize an in-use device.

Type: String

verificationUri

The URI of the verification page that takes the userCode to authorize the device.

Type: String

verificationUriComplete

An alternate URL that the client can use to automatically launch a browser. This process skips the manual step in which the user visits the verification page and enters their code.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServerException

Indicates that an error from the service occurred while trying to process a request.

error: Single error code. For this exception the value will be server_error.
error_description: Human-readable text providing additional information, used to assist the client developer in understanding the error that occurred.

HTTP Status Code: 500

InvalidClientException

Indicates that the clientId or clientSecret in the request is invalid. For example, this can occur when a client sends an incorrect clientId or an expired clientSecret.

error: Single error code. For this exception the value will be invalid_client.
error_description: Human-readable text providing additional information, used to assist the client developer in understanding the error that occurred.

HTTP Status Code: 401

InvalidRequestException

Indicates that something is wrong with the input to the request. For example, a required parameter might be missing or out of range.

error: Single error code. For this exception the value will be invalid_request.
error_description: Human-readable text providing additional information, used to assist the client developer in understanding the error that occurred.

HTTP Status Code: 400

SlowDownException

Indicates that the client is making the request too frequently and is more than the service can handle.

error: Single error code. For this exception the value will be slow_down.
error_description: Human-readable text providing additional information, used to assist the client developer in understanding the error that occurred.

HTTP Status Code: 400

UnauthorizedClientException

Indicates that the client is not currently authorized to make the request. This can happen when a clientId is not issued for a public client.

error: Single error code. For this exception the value will be unauthorized_client.
error_description: Human-readable text providing additional information, used to assist the client developer in understanding the error that occurred.

HTTP Status Code: 400