Security Resources

{excerpt}This document describes the API of the security part, that allows for example to login and log out a user.{excerpt}
{toc:maxLevel=2}

h1. Resources

h2. Create Security Session (Log in)

This resource allows you to create a new security session, or in other words to log in at the platform. With a successful login, a security session will be created at the platform for you, and the security sessionId will be returned in the location header. You can use this security sessionId to access sessionId protected resources, such as user resources (see [SprdAuth protocol|API:Security] for more information). Use HTTPS when conducting requests on this resource.


|| Url | .../v1/sessions ||
|| Sample | [https://api.spreadshirt.net/api/v1/sessions] ||
|| Type | List ||
|| Method | POST ||
|| Special Status Codes | ||

*Request Representation:*

{noformat}
<login xmlns:xlink="http://www.w3.org/1999/xlink" 
xmlns="http://api.spreadshirt.net">  
...
</login>
{noformat}

See *[Login Representation|#Login]*


*Response Representation:*

Header:

{noformat}Location: .../v1/sessions/70aab75c0b6217c2aff1fe301111929291{noformat}

h2. Retrieve Security Session

This resource allows to check whether a security session exists.

|| Url | .../v1/sessions/\{sessionId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/sessions/70aab75c0b6217c2aff1fe301111929291] ||
|| Type | Entity ||
|| Method | GET ||
|| Special Status Codes | ||
|| APIKey | ||
|| SessionId | ||

*Response Representation:*

{code}
<session>
...
</session>
{code}

See [Session Representation|#Session]

This resource allows you to delete an open security session, or in other words to log out at the platform. Please note that security sessions also expire automatically if the session is no longer used.


|| Url | .../v1/sessions/\{sessionId\} ||
|| Sample | [http://api.spreadshirt.net/api/v1/sessions/70aab75c0b6217c2aff1fe301111929291] ||
|| Type | Entity ||
|| Method | DELETE ||
|| Special Status Codes | ||

h1. Representations

h2. Login

|| Field || Description \\ ||
| login \\ | |
| login/username \\ | *Your Spreadshirt userId or e-mail address.* \\ |
| login/password \\ | The plain text password of your Spreadshirt user. \\ |

Example:
{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

{code}

h2. Session

|| Field || Description ||
| session | Representation of a platform session. |
| session/user | Reference to the user that the session belongs to. |

Example:
{code}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<session xmlns="http://api.spreadshirt.net"
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://api.spreadshirt.net/api/v1/sessions/26bdd278-b678-4ccc-931e-0a26d30befeb"
id="26bdd278-b678-4ccc-931e-0a26d30befeb">
<user xlink:href="http://api.spreadshirt.net/api/v1/users/1102730" id="1102730"/>
</session>
{code}

h1. Use Cases

h2. Log in and Access Protected User Products List

!Session Usage.png!

h3. 1. + 2. Retrieve User Products List without valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=...

Status Code: 401 (sessionId does not exist - means user not logged in\!)

h3. 3. + 4. Log in/ Create Security Session

Resource: POST .../sessions

Request Representation:
{code}
<login xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net"> <username>Spreadshirt</username>
<password>spreadshirt</password>
</login>
{code}

Status Code: 201 Session Created (Logged in)

Response Representation:

Header:
{noformat}
Location: .../sessions/456
{noformat}

h3. 5. + 6. Retrieve User Products with valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=456

Status Code: 200

Response Representation:

{noformat}
<products...>
...
</products>
{noformat}

h2. Logout and Access Protected User Products List

!Session Usage Logout.png!

h3. 1. + 2. Retrieve User Products List with valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=456

Status Code: 200

Response Representation:

{noformat}
<products...>
...
</products>
{noformat}

h3. 3. + 4. Logout/ Delete Security Session

Resource: DELETE .../sessions/456

Status Code: 200 (Logged out/ Deleted session)

h3. 5. + 6. Retrieve User Products List without valid SessionId

Resource: GET .../users/123/products?apiKey=...&sig=...&time=...&sessionId=...

Status Code: 401 (sessionId does not exist - means user not logged in\!)