AssumeRoleForPodIdentity - Amazon EKS


The Amazon EKS Auth API and the AssumeRoleForPodIdentity action are only used by the EKS Pod Identity Agent.

We recommend that applications use the AWS SDKs to connect to AWS services; if credentials from an EKS Pod Identity association are available in the pod, the latest versions of the SDKs use them automatically.

Request Syntax

POST /clusters/clusterName/assume-role-for-pod-identity HTTP/1.1 Content-type: application/json { "token": "string" }

URI Request Parameters

The request uses the following URI parameters.


The name of the cluster for the request.

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: [0-9A-Za-z][A-Za-z0-9\-_]*

Required: Yes

Request Body

The request accepts the following data in JSON format.


The token of the Kubernetes service account for the pod.

Type: String

Length Constraints: Minimum length of 1.

Pattern: [A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+

Required: Yes

Response Syntax

HTTP/1.1 200 Content-type: application/json { "assumedRoleUser": { "arn": "string", "assumeRoleId": "string" }, "audience": "string", "credentials": { "accessKeyId": "string", "expiration": number, "secretAccessKey": "string", "sessionToken": "string" }, "podIdentityAssociation": { "associationArn": "string", "associationId": "string" }, "subject": { "namespace": "string", "serviceAccount": "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.


An object with the permanent IAM role identity and the temporary session name.

The ARN of the IAM role that the temporary credentials authenticate to.

The session name of the temporary session requested to AWS STS. The value is a unique identifier that contains the role ID, a colon (:), and the role session name of the role that is being assumed. The role ID is generated by IAM when the role is created. The role session name part of the value follows this format: eks-clustername-podname-random UUID

Type: AssumedRoleUser object


The identity that is allowed to use the credentials. This value is always

Type: String


The AWS Signature Version 4 type of temporary credentials.

Type: Credentials object


The Amazon Resource Name (ARN) and ID of the EKS Pod Identity association.

Type: PodIdentityAssociation object


The name of the Kubernetes service account inside the cluster to associate the IAM credentials with.

Type: Subject object


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


You don't have permissions to perform the requested operation. The IAM principal making the request must have at least one IAM permissions policy attached that grants the required permissions. For more information, see Access management in the IAM User Guide.

HTTP Status Code: 400


The specified Kubernetes service account token is expired.

HTTP Status Code: 400


These errors are usually caused by a server-side issue.

HTTP Status Code: 500


The specified parameter is invalid. Review the available parameters for the API request.

HTTP Status Code: 400


This exception is thrown if the request contains a semantic error. The precise meaning will depend on the API, and will be documented in the error message.

HTTP Status Code: 400


The specified Kubernetes service account token is invalid.

HTTP Status Code: 400


The specified resource could not be found.

HTTP Status Code: 404


The service is unavailable. Back off and retry the operation.

HTTP Status Code: 503


The request was denied because your request rate is too high. Reduce the frequency of requests.

HTTP Status Code: 429


In the following example or examples, the Authorization header contents (AUTHPARAMS) must be replaced with an AWS Signature Version 4 signature. For more information about creating these signatures, see Signature Version 4 Signing Process in the Amazon EKS General Reference.

You need to learn how to sign HTTP requests only if you intend to manually create them. When you use the AWS Command Line Interface (AWS CLI) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you configure the tools. When you use these tools, you don't need to learn how to sign requests yourself.


The following example assumes an IAM role with the EKS Pod Identity association called my-association in a cluster called my-cluster.

Sample Request

POST /clusters/my-cluster/assume-role-for-pod-identity HTTP/1.1 Host: Accept-Encoding: identity User-Agent: aws-cli/1.29.81 md/Botocore#1.31.81 ua/2.0 os/macos#22.6.0 md/arch#x86_64 lang/python#3.8.0 md/pyimpl#CPython cfg/retry-mode#legacy botocore/1.31.81 X-Amz-Date: 20231121T192727Z Authorization: AUTHPARAMS Content-length: 1043 { "token": "eyJhbEXAMPLE" }

Sample Response

HTTP/1.1 200 OK Date: Fri, 22 Mar 2019 16:01:58 GMT Content-Type: application/json Content-Length: 682 x-amzn-RequestId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx x-amz-apigw-id: W84GUEIbPHcFW2Q= X-Amzn-Trace-Id: Root=1-xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx Connection: keep-alive { "assumedRoleUser": { "arn": "arn:aws:sts::012345678910:assumed-role/my-role/eks-my-cluster-podname-randomUUID", "assumeRoleId": "AROA123456789EXAMPLE:eks-my-cluster-podname-randomUUID" }, "audience": "", "credentials": { "accessKeyId": "ASIAIOSFODNN7EXAMPLE", "expiration": 1.70061547E9, "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "sessionToken": "EXAMPLE" }, "podIdentityAssociation": { "associationArn": "arn:aws:eks:us-west-2:012345678910:podidentityassociation/my-association/a-abcdefghijklmnop1", "associationId": "a-abcdefghijklmnop1" }, "subject": { "namespace": "my-namespace", "serviceAccount": "my-serviceaccount" } }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: