CreateSession
Creates a session that establishes temporary security credentials to support fast authentication and authorization for the Zonal endpoint APIs on directory buckets. For more information about Zonal endpoint APIs that include the Availability Zone in the request endpoint, see S3 Express One Zone APIs in the Amazon S3 User Guide.
To make Zonal endpoint API requests on a directory bucket, use the CreateSession
API operation. Specifically, you grant s3express:CreateSession
permission to a
bucket in a bucket policy or an IAM identity-based policy. Then, you use IAM credentials to make the
CreateSession
API request on the bucket, which returns temporary security
credentials that include the access key ID, secret access key, session token, and
expiration. These credentials have associated permissions to access the Zonal endpoint APIs. After
the session is created, you don’t need to use other policies to grant permissions to each
Zonal endpoint API individually. Instead, in your Zonal endpoint API requests, you sign your requests by
applying the temporary security credentials of the session to the request headers and
following the SigV4 protocol for authentication. You also apply the session token to the
x-amz-s3session-token
request header for authorization. Temporary security
credentials are scoped to the bucket and expire after 5 minutes. After the expiration time,
any calls that you make with those credentials will fail. You must use IAM credentials
again to make a CreateSession
API request that generates a new set of
temporary credentials for use. Temporary credentials cannot be extended or refreshed beyond
the original specified interval.
If you use AWS SDKs, SDKs handle the session token refreshes automatically to avoid service interruptions when a session expires. We recommend that you use the AWS SDKs to initiate and manage requests to the CreateSession API. For more information, see Performance guidelines and design patterns in the Amazon S3 User Guide.
Note
-
You must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide. -
CopyObject
API operation - Unlike other Zonal endpoint APIs, theCopyObject
API operation doesn't use the temporary security credentials returned from theCreateSession
API operation for authentication and authorization. For information about authentication and authorization of theCopyObject
API operation on directory buckets, see CopyObject. -
HeadBucket
API operation - Unlike other Zonal endpoint APIs, theHeadBucket
API operation doesn't use the temporary security credentials returned from theCreateSession
API operation for authentication and authorization. For information about authentication and authorization of theHeadBucket
API operation on directory buckets, see HeadBucket.
- Permissions
-
To obtain temporary security credentials, you must create a bucket policy or an IAM identity-based policy that grants
s3express:CreateSession
permission to the bucket. In a policy, you can have thes3express:SessionMode
condition key to control who can create aReadWrite
orReadOnly
session. For more information aboutReadWrite
orReadOnly
sessions, seex-amz-create-session-mode
. For example policies, see Example bucket policies for S3 Express One Zone and AWS Identity and Access Management (IAM) identity-based policies for S3 Express One Zone in the Amazon S3 User Guide.To grant cross-account access to Zonal endpoint APIs, the bucket policy should also grant both accounts the
s3express:CreateSession
permission. - HTTP Host header syntax
-
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
Request Syntax
GET /?session HTTP/1.1
Host: Bucket
.s3.amazonaws.com
x-amz-create-session-mode: SessionMode
URI Request Parameters
The request uses the following URI parameters.
- Bucket
-
The name of the bucket that you create a session for.
Required: Yes
- x-amz-create-session-mode
-
Specifies the mode of the session that will be created, either
ReadWrite
orReadOnly
. By default, aReadWrite
session is created. AReadWrite
session is capable of executing all the Zonal endpoint APIs on a directory bucket. AReadOnly
session is constrained to execute the following Zonal endpoint APIs:GetObject
,HeadObject
,ListObjectsV2
,GetObjectAttributes
,ListParts
, andListMultipartUploads
.Valid Values:
ReadOnly | ReadWrite
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 200
<?xml version="1.0" encoding="UTF-8"?>
<CreateSessionOutput>
<Credentials>
<AccessKeyId>string</AccessKeyId>
<Expiration>timestamp</Expiration>
<SecretAccessKey>string</SecretAccessKey>
<SessionToken>string</SessionToken>
</Credentials>
</CreateSessionOutput>
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in XML format by the service.
- CreateSessionOutput
-
Root level tag for the CreateSessionOutput parameters.
Required: Yes
- Credentials
-
The established temporary security credentials for the created session.
Type: SessionCredentials data type
Errors
- NoSuchBucket
-
The specified bucket does not exist.
HTTP Status Code: 404
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: