Apps/WebApplicationReceipt/SigningService

General Info

Definitions

endpoint-url 

The full URI for the service including the version string for the API as defined below

version string 

This revision of the protocol is 1.0 so the version string is "/1.0/"

Abbreviations

JWK 

JSON Web Key

JWS 

JSON Web Signature

JWT 

JSON Web Token

Data format

receipt input 

Input is expected to be in a plaintext JWT format with additional fields as defined by the Web Application Receipt wiki page. Since it is a JWT format, UTF-8 is REQUIRED.

{
 typ: "purchase-receipt",
 product: {
   url: "https://grumpybadgers.com",
   storedata: "5169314356"
 },
 user: {
   type: "email",
   value: "pseud-123gBm51jc56s@idprovider.com"
 },
 iss: "https://appstore.com",
 nbf: 131360185,
 iat: 131360188,
 detail: "https://appstore.com/receipt/5169314356",
 verify: "https://appstore.com/verify/5169314356"
}

API

POST http

//<endpoint-url>/sign : Takes a receipt in the Receipt format. Returns a BrowserID style certificate chain followed by the signed receipt.

<root key certificate>"~"<ephemeral key certificate>"~"<signed receipt>

Definitions

root key certificate 

a JWS encoded JWK that is self-signed

ephemeral key certificate 

a JWS encoded JWK that is signed by the root key and can be verified with the root key certificate

signed receipt 

a JWT that is signed by the current ephemeral key certificate

HTTP response codes

200 OK 

The request was processed successfully and the server is returning a signed receipt

400 Bad Request 

The request itself is malformed or the data supplied with the request is invalid.

401 Unauthorized 

The authentication credentials are invalid. At the moment authorization consists of a simple whitelist of IPs. In the future this may be used to indicate a BrowserID or other authentication mechanism has failed or the credentials are not authorized to use the service.

409 Conflict 

The nbf, iat, or iss specified in the input are invalid for the root key(in the case of a mismatching iss) or the nbf or iat fields are outside the ephemeral key's window of signing validity.

503 Service Unavailable 

Indicates that the server(s) are undergoing maintenance.