Create Session

Important

Session-based authentication is currently in preview. Your subscription must be enabled for preview before you can use the Create Session operation.

Create Session operation creates a five minute session that's scoped to a container. A session provides credentials that can be used to authorize subsequent requests to resources within that container.

Sessions are intended for workloads that perform multiple requests against the same container and can reduce the authentication and authorization processing required for subsequent requests.

Request

You can construct the Create Session request as follows. HTTPS is required.

Method	Request URI	HTTP version
`POST`	`https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=session`	HTTP/1.1

Replace myaccount with the name of your storage account and mycontainer with the name of the container for which the session is created.

URI parameters

The following parameters are required on the request URI.

Parameter	Description
`restype`	Required. Must be container. Specifies that the request applies to the container resource.
`comp`	Required. Must be session. Specifies the Create Session operation.

Request headers

The following request headers are required:

Request header	Description
`Authorization`	Required. Authorizes the Create Session request by using a Microsoft Entra access token.
`Date` or `x-ms-date`	Required. Specifies the Coordinated Universal Time (UTC) for the request.
`x-ms-version`	Required. Specifies the version of the operation to use for this request. Create Session is only supported in version `2026-02-06` or later. For more information, see Versioning for the Azure Storage services.

Create Session must be authorized by using a Microsoft Entra access token. Session based authorization can't be used to create a session.

Request body

The request body has the following XML format:

<?xml version="1.0" encoding="utf-8"?>
<CreateSessionRequest>
  <AuthenticationType>HMAC</AuthenticationType>
</CreateSessionRequest>

The following table describes the elements of the request body.

Element	Required	Description
`AuthenticationType`	Yes	Specifies the authentication mechanism for requests that use the session. The currently supported value is HMAC. When HMAC is specified, Create Session returns a session key that the client uses to sign subsequent requests.

Sample request

POST /mycontainer?restype=container&comp=session HTTP/1.1
Host: myaccount.blob.core.windows.net
Authorization: Bearer {Microsoft Entra access token}
x-ms-date: {date}
x-ms-version: {version}
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<CreateSessionRequest>
  <AuthenticationType>HMAC</AuthenticationType>
</CreateSessionRequest>

Response

A successful operation returns status code 201 (Created).

Response body

The response body contains information and credentials for the newly created session.

<?xml version="1.0" encoding="utf-8"?>
<CreateSessionResult>
  <Id>4e6a585b-5fd9-49f5-aa81-014a9dbaa5cc</Id>
  <Expiration>2025-08-25T19:48:17.8038151Z</Expiration>
  <AuthenticationType>HMAC</AuthenticationType>
  <Credentials>
    <SessionToken>aB1cD2eF-3gH4iJ5kL6-mN7oP8qR=</SessionToken>
    <SessionKey>aaaaaaaa0b0b1c1c2d2d333333333333==</SessionKey>
  </Credentials>
</CreateSessionResult>

The response includes the following elements:

Element	Description
`Id`	A unique identifier for the session.
`Expiration`	The time at which the session expires.
`AuthenticationType`	The authentication mechanism associated with the session.
`Credentials`	Contains the credentials required to authorize requests using the session.
`SessionToken`	An opaque token used to authorize subsequent requests in the session. Treat the session token as a security credential.
`SessionKey`	For an HMAC session, the symmetric key used to sign requests using the Shared Key signing protocol. Treat the session key as a security credential.

Authorization

Create Session requires Microsoft Entra ID authorization.

Authorize the request with a Microsoft Entra access token.

The session is scoped to the container specified in the request URI and doesn't grant permissions beyond those assigned to the Microsoft Entra security principal. The principal must have permission to perform Get Blob for the requested resource.

Using the session with Get Blob

For an HMAC session, use the returned SessionToken and SessionKey to authorize subsequent Get Blob requests.

The client signs the request using the session key and includes the resulting signature and session token in the Authorization header:

Authorization: Session {SessionToken}:{Signature}

For example:

GET /mycontainer/myblob HTTP/1.1
Host: myaccount.blob.core.windows.net
Authorization: Session {SessionToken}:{Signature}
x-ms-version: {version}

The session is scoped to the container for which it was created.

Session lifetime and renewal

A session expires after five minutes but can become invalid earlier if the oauth token supplied expires sooner. Clients should obtain a new session when the current session is expiring or no longer valid.

Session status

Responses to requests that use session authorization can contain session status information.

Session status	Description
`session_expiring`	The session is about to expire or become invalid. The client should obtain a new session before the existing session becomes unusable.
`session_expired`	The session has expired, wasn't found, or was revoked. The session can no longer be used. The client should create a new session.
`session_token_invalid`	The supplied session token is malformed or otherwise syntactically invalid.

The session_expiring status can be returned in the x-ms-auth-info response header.

When session authorization fails with 401 Unauthorized, the service can return session error information in the WWW-Authenticate header.

A request can also fail with 403 Forbidden when the supplied session is valid but doesn't authorize the requested resource or operation.

Remarks

Context

When a session is created, Azure Blob Storage evaluates the caller's Microsoft Entra identity and applicable RBAC and ABAC permissions. Subsequent requests are authorized using this session context.

Scope

A session is scoped to the container specified in the Create Session request and can't be used to access other containers. It doesn't grant permissions beyond those of the identity that created it.

Permission changes made during the session lifetime take effect when a new session is created.

Permission evaluation

Create Session evaluates authorization when the session is created. Changes to the account, container, or permissions aren't reflected in an existing session. The changes are reflected when a new session is created after the existing five-minute session expires.

Network context

A session retains the network context that applies when the session is created. Subsequent requests that use the session must originate from the same client IP address. Requests from a different client IP address are rejected.

Security

SessionToken and SessionKey are security credentials and should be protected from disclosure.

Limitations

Session-based authentication currently supports only the Get Blob operation. The following scenarios aren't supported:

Blob tags with Get Blob requests that use session credentials.
Get Blob requests to secondary accounts.
Microsoft Purview with session credentials.

Other Blob Storage operations must use an existing supported authorization mechanism.

Billing

Pricing requests can originate from clients that use Blob Storage APIs, either directly through the Blob Storage REST API or through an Azure Storage client library. These requests accrue charges per transaction. The transaction type determines how the account is charged. For example, read transactions accrue charges in a different billing category than write transactions.

The following table shows the billing category for Create Session requests based on the storage account type:

Operation	Storage account type	Billing category
Create Session	Premium block blob Standard general-purpose v2 Standard general-purpose v1	Write operations

To learn about pricing for the specified billing category, see Azure Blob Storage pricing.

Last updated on 2026-10-29