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.
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.
Deprecated is the usage of query parameters to pass security credentials:
- 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.
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:
Header would be:
Query data would be: