|Table of Contents|
The Spreadshirt API security concept consists of two parts:
- APIKeys - An API key is issued by Spreadshirt and assigned to a developer that wants to work on the Spreadshirt API. An API key consists of a key and a secret. The key is usually provided when conducting API calls. The secret is used to calculate a specific signature per request. The API key authenticates a specific developer that wants to access an API resource and is used to authorize that request.
The API provides certain unprotected and protected resources. Protected resources are usually resources that provide access to user data as well as all resources that allow to add, update or delete data. Protected resources are usually at least API key protected, which means you need to provide the API key and a set of security credentials in order to access such resources.
- SessionIds - A sessionId is issued by Spreadshirt when a customer logs in at the platform using for example the API (see Security Resources for details). The sessionId authenticaes a specific customer that wants to access an API resource and is used to authorize that request.
The API provides unproteced and protected resources. Protected resources that require the existence of a sessionId are usually resources that provide access to user data. For those resources, you need to provide the sessionId in the request data.
Therefore, protected resources can be protected
- with an APIKey and a SessionId,
- with an APIKey only,
- with a SessionId only.
To exchange security information between client and server, we use the SprdAuth security protocol. In the following sections, we describe the SprdAuth protocol in detail.
Meaning of Request/Response Headers and Parameters
SprdAuth protocol works in general based on the HTTP protocol's Authorization request header and the WWW-Authenticate response header. However, as certain clients can't send HTTP headers, one can also provide the required information in the URI's query part.
The relevant request headers and parameters for security are:
- Authorization - The standard HTTP Authorization header is used to provide authentication information in a HTTP request, such as APIkey and sessionId. The header usually contains the API key, the request data, a signature calculated based on the request data and the secret and optionally a sessionId. SprdAuth thereby tells the server that we are talking SprdAuth protocol during the authorization.
Authorization: SprdAuth apiKey="<apikey>", data="<method> <url> <time>", sig="SHA1(<method> <url> <time> <secret>)", sessionId="<sessionId>"
- apiKey - The query parameter apiKey contains the API key information for those cases, where HTTP header Authorization can not be used.
- sig - The query parameter sig contains the calculated request signature for those cases, where HTTP header Authorization can not be used.
- time - The query parameter time contains the request time for those cases, where HTTP header Authorization can not be used.
- sessionId - The query parameter sessionId contains the request session id for those cases, where HTTP header Authorization can not be used.
http://...?apiKey=<apikey>&sig=SHA1(<method> <url> <time> <secret>)&time=<time>&sessionId=<sessionId>
The relevant response headers are:
- WWW-Authenticate - The standard HTTP WWW-Authenticate header is usually returned when API request authorization failed and status code 401 (unauthorized) was returned. It contains in our case the string SprdAuth, that tells the you, that you need to use SprdAuth protocol in order to provide your security credentials.
Please note that SHA1(..) means you need to apply SHA1 algorithm to the string and provide the hex representation of the result.
SprdAuth Security Protocol
The SprdAuth protocol works as follows in case a client wants to access a protected resource:
Request without Authentication Info
Request with Authentication Info in Header
Request with Authentication Info in Query
The API allows only times that are between one hour before and one hour after the current server time. In case you programm client applications, e.g. flash clients, don't use the clients time - you can't be sure that the clients clock goes right - but use the time of the server's HTTP response headers instead!
Example APIKey + SessionId:
You call POST http://localhost:8080/api/v1/users/42/productPriceCalculator.
Your API key is: 123456789 Your Secret is: 987654321 Your session id is: 123 Data is: POST http://localhost:8080/api/v1/users/42/productPriceCalculator 1240575575156 Data for signing is: POST http://localhost:8080/api/v1/users/42/productPriceCalculator 1240575575156 987654321 Signature is SHA1 as Hey: 70aab75c0b6217c2aff1f896bd4081fe30920911
Header would be:
Authorization: SprdAuth apiKey="123456789", \ data="POST http://localhost:8080/api/v1/users/42/productPriceCalculator 1240575575156", \ sig="70aab75c0b6217c2aff1f896bd4081fe30920911", sessionId="123"
Query data would be: