Microsoft.Azure.Batch.SoftwareEntitlement.Server

REST API for the Software Entitlement Service

Reference documentation for the current version of the REST API supported by the Software Entitlement Service. For historical versions and a list of changes, see the end of this document.

⚠️ This is draft documentation for the next version of the SES REST API - see the previous version for the current release.

Token Verification

Verifies that a provided software entitlement token grants permission to use a specific application.

REQUEST

Method	Request URI
POST	{endpoint}/softwareEntitlements/?api-version={version}

Sample: https://samples.westus.batch.azure.com/softwareEntitlements/?api-version=2017-99-99-9.9

Placeholder	Type	Description
endpoint	string	The Batch account URL endpoint supplied by Azure Batch via the environment variable AZ_BATCH_ACCOUNT_URL. This may have a trailing / (e.g. https://demo.westus.batch.azure.com/) or it might not (e.g. https://demo.westus.batch.azure.com); clients should be prepared to handle either case correctly.
version	string	The API version of the request. Specify version 2017-99-99.9.9 or higher. For older API versions, see the end of this document. All Batch API versions are listed @ https://docs.microsoft.com/en-us/rest/api/batchservice/batch-service-rest-api-versioning

The following shows a sample JSON payload for the request:

{
    "token": "...",
    "applicationId": "contosoapp"
}

Element	Required	Type	Description
token	Mandatory	string	The software entitlement token supplied to the software package via environment variable from Azure Batch
applicationId	Mandatory	string	A unique identifier for the application requesting an entitlement to run. Samples: contosoapp, application Application identifiers are lowercase (though comparisons will be case-insensitive), with no punctuation, whitespace or non-alpha characters.

Specific unique application identifiers for each software package will be agreed between Azure Batch and the software vendor in advance, prior to integration.

RESPONSE 200 - OK

If the token grants permission to the requested application, the service will return HTTP Status 200 and the response body will contain details of the entitlement.

The following example shows a sample JSON response:

{
    "id": "entitlement-24223578-1CE8-4168-91E0-126C2D5EAA0B",
    "expiry": "2017-07-21T01:47:38.4420202Z"
}

Element	Required	Type	Description
id	Mandatory	string	A unique identifier for the specific entitlement issued to the application. Multiple entitlement requests for the same application from the same compute node may (but are not required to) return the same identifier. Entitlement requests from different compute nodes will not return duplicate identifiers. Clients should make no assumptions about the structure of the id as it may change from release to release.
expiry	Mandatory	DateTime	The timestamp when the token expires. Once the token has expired, further verification requests will be declined.

RESPONSE 403 - FORBIDDEN

If the token does not grant permission to use the requested application, the service will return HTTP status 403 and the response body will contain extended error information.

An entitlement request may be denied if:

• The token has already expired;
• The requested application is not included in the token; or
• The token was issued to a different compute node.

The following example shows a sample JSON response:

{
    "code": "EntitlementDenied",
    "message":
    {
        "lang": "en-us",
        "value": "Software entitlement for 'contosoapp' was denied."
    }
}

See Batch status and error codes for more information.

RESPONSE 400 - BAD REQUEST

The service will return HTTP status 400 and the response body will be empty if:

• The software entitlement token is missing, invalid, corrupt, or missing any mandatory fields;
• The request is badly formed; or
• The api-version specified on the URL is invalid.

RESPONSE 404 - NOT FOUND

The service will return HTTP status 404 if the URL is malformed.

The most common cause for this is code that always adds a separating / to the end of the URL provided in AZ_BATCH_ACCOUNT_URL without checking to see if a trailing / is already present.

E.g. if AZ_BATCH_ACCOUNT_URL is set to https://demo.westus.batch.azure.com/ and the client appends /softwareEntitlements/?api-version=2017-99-99-9.9 then the resulting URL of https://demo.westus.batch.azure.com//softwareEntitlements/?api-version=2017-99-99-9.9 (containing a double //) will be invalid.

Historical Versions

For prior versions of the REST API, see the following pages:

• Initial release, July 2017: API Version 2017-05-01.5.0

Changes in this version

Changes in this version of the REST API are:

• Removal of the vmid value from the response to a successful entitlement verification request.
• Addition of the expiry value to the response, giving visibility of the scheduled token expiry.