Developer Guide

Authorizing Direct Calls to AWS Services

Devices may use X.509 certificates to connect to AWS IoT using TLS mutual authentication protocols. Other AWS services do not support certificate-based authentication, but they can be called using AWS credentials in Signature Version 4 format. After authenticating a device with a certificate, AWS IoT can assume a role on behalf of the device and request temporary credentials from IAM. The device can then use that credential to call other AWS services.

Requests for temporary credentials can be made with an HTTP GET on port 443, for example:



To find your endpoint, use the describe-endpoint CLI command specifying iot:CredentialProvider as the endpoint type.

To make sure your device is communicating with AWS IoT (and not a service impersonating it), copy the Amazon Root CA 1 for RSA, and the VeriSign Class 3 Public Primary G5 root CA certificate to your device.

When making a request for temporary credentials, you can optionally provide a thing name in a request header called x-amzn-iot-thingname. In order to use thingName in a request header you must attach the thing to a device certificate using the AttachThingPrincipal API. When a device requests credentials by passing the thingName, AWS IoT checks that the thingName is attached to the certificate presented during the TLS handshake and will not provide temporary credentials unless it is.

Passing the thing name in the request allows you to use thingName and thingType as policy variables in the role’s access policy for fine-grained access. For more information, see AWS IoT Policy Variables. You cannot use thing variables in policies unless a thing name is passed in the request header.

The policy attached to the device certificate must grant the device permission to assume the role. You do this by granting permission for the iot:AssumeRoleWithCertificate action on the ARN of the role alias, for example arn:aws:iot:<your-region>:<your-aws-account-id>:rolealias/<role-alias-name>

You grant privileges to the temporary credentials by creating an IAM role and attaching policies to it. You can have fine-grained control over the privileges granted to this role by using policy variables thingName, thingType and certificateId. For more information, see AWS IoT Policy Variables.

The device which is going to make direct calls to AWS Services must know what role ARN to use when connecting to AWS IoT. But hard-coding the role ARN is not a good solution because you would have to update the device anytime the role ARN changes. A better solution is to create a role alias that points to the role ARN and use that on your device. If the role ARN changes, you can update the role alias and no change is required on the device. Role aliases are created using the CreateRoleAlias API. This API takes the following parameters:


How long (in seconds) the credential is valid.


An arbitrary string identifying the role alias. Must be 1-128 characters and must include only A-Za-z0-9=,@- characters.


The ARN of the role to which the role alias refers.

Note that the entity which performs the CreateRoleAlias must have sufficient privileges of its own to do so. Specifically, it must have an attached policy that allows the iam:PassRole action on the ARN of the created IAM role which is to be aliased.

You can pass a thing name in a request header when requesting temporary credentials. If the thing name is present, you can use thing policy variables to scope-down the credential returned by AWS IoT.

ThingName is an optional request parameter, which can be passed through an HTTP request header called x-amzn-iot-thingname.

Requests to AWS IoT for temporary credentials are made to port 443 over HTTP with TLS mutual authentication. This request must be an HTTP GET request. The URL is similar to: