...
| Code Block |
|---|
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"reason":"You must sign the Synapse terms of use."}
|
The API for retrieving the text of the terms of use is given below.
Session token is valid for a period of time, currently set to 24 hours.
Refresh Token (reset timer)
Request:
| Code Block |
|---|
PUT https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 No Content
|
Error Response, if the session token is invalid:
| Code Block |
|---|
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
|
Terminate Session (Logout)
Note: Sessions initiated by multiple clients for the same user around the same time will receive identical "single sign on" tokens. Since session termination is linked to the session token, terminating the session for one client via this command will have the side effect of terminating all sessions. An alternative is for the client simply to delete its own copy of the token.
Request:
| Code Block |
|---|
DELETE<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns:mv="http://macVmlSchemaUri" xmlns="http://www.w3.org/TR/REC-html40"> <head> <meta name=Title content="Synapse Terms and Conditions of Use"> <meta name=Keywords content=""> ... </html> |
ie. the text of the terms of use is included in the response.
Session token is valid for a period of time, currently set to 24 hours.
Refresh Token (reset timer)
Request:
| Code Block |
|---|
PUT https://auth-staging.sagebase.org/auth/v1/session
|
Note: Session token is required in request header.
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 204 NONo CONTENTContent |
Sample commands, issued from cURL:
Create User:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"firstName\":\"demoError Response, if the session token is invalid:
| Code Block |
|---|
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
|
Terminate Session (Logout)
Note: Sessions initiated by multiple clients for the same user around the same time will receive identical "single sign on" tokens. Since session termination is linked to the session token, terminating the session for one client via this command will have the side effect of terminating all sessions. An alternative is for the client simply to delete its own copy of the token.
Request:
| Code Block |
|---|
DELETE https://auth-staging.sagebase.org/auth/v1/session
|
Note: Session token is required in request header.
Response:
| Code Block |
|---|
HTTP/1.1 204 NO CONTENT
|
Sample commands, issued from cURL:
Create User:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"firstName\":\"demo\", \"lastName\":\"user\", \"displayName\":\"Demo User\"}" -X POST https://auth-staging.sagebase.org/auth/v1/user
...
Logout:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X DELETE https://auth-staging.sagebase.org/auth/v1/session
Access repository services anonymously:
curl -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/dataset/test
Access repository services with session token (obtained by logging in):
curl -H Accept:application/json -H sessionToken:AprxPRzpmaPm7FXzV1ik0w00 https://repo-staging.sagebase.org/repoauth/v1/dataset/testsession
Access repository services with HMAC-SHA1 signed requestanonymously:
curl -i -H "Content-Type:application/json" -H " Accept:application/json " -H signatureTimestamp:2011-09-27T21:59:22.371-07:00 -H signature:yhMgokIH9ErQklj8oUuhHR5o5QM= -H userId:demouser@sagebase.org -X GET "httphttps://localhost:8080/services-repository-0.7-SNAPSHOTrepo-staging.sagebase.org/repo/v1/dataset?sort=name&limit=3"
Authentication of Requests to Platform
Authentication via Session Token
Requests shall include a header named "sessionToken" whose value is that returned by the Initiate Session request, above. (The session will timeout eventually, with a nominal duration of 24 hours.)
Authentication via Secret Key
Request shall include the following headers:
| Code Block |
|---|
userId: demouser@sagebase.org
signatureTimestamp: 2011-07-16T19:20:30.45+01:00 (i.e. in ISO8601 format including time zone)
signature: <signature>
|
where <signature> is the HMAC-SHA1 hash created using the shared secret key generated above, and the hashed data is the concatenation:
userId + uri + signatureTimestamp
URI example: If the request is made to
https://repo-staging.sagebase.org/test
Access repository services with session token (obtained by logging in):
curl -H Accept:application/json -H sessionToken:AprxPRzpmaPm7FXzV1ik0w00 https://repo-staging.sagebase.org/repo/v1/dataset/test
Access repository services with HMAC-SHA1 signed request:
curl -i -H "Content-Type:application/json" -H "Accept:application/json" -H signatureTimestamp:2011-09-27T21:59:22.371-07:00 -H signature:yhMgokIH9ErQklj8oUuhHR5o5QM= -H userId:demouser@sagebase.org -X GET "http://localhost:8080/services-repository-0.7-SNAPSHOT/repo/v1/dataset?sort=name&limit=3
then the URI is:
/repo/v1/dataset
Authentication Failure
For requests that fail to be authenticated the response will include the headers:
WWW-Authenticate: authenticate Crowd
and a plain text body: "The token provided was invalid or expired."
API for Terms of Use
A user may not initiate a session until they agree to the Synapse Terms of Use. This API allows retrieval of the terms.
Get the Terms of Use
| Code Block |
|---|
GET https://auth-staging.sagebase.org/auth/v1/termsOfUse
|
Successful Response:
| Code Block |
|---|
HTTP/1.1 200 OK
<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns:m="http://schemas.microsoft.com/office/2004/12/omml"
xmlns:mv="http://macVmlSchemaUri" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta name=Title content="Synapse Terms and Conditions of Use">
<meta name=Keywords content="">
...
</html>
|
"
Authentication of Requests to Platform
Authentication via Session Token
Requests shall include a header named "sessionToken" whose value is that returned by the Initiate Session request, above. (The session will timeout eventually, with a nominal duration of 24 hours.)
Authentication via Secret Key
Request shall include the following headers:
| Code Block |
|---|
userId: demouser@sagebase.org
signatureTimestamp: 2011-07-16T19:20:30.45+01:00 (i.e. in ISO8601 format including time zone)
signature: <signature>
|
where <signature> is the HMAC-SHA1 hash created using the shared secret key generated above, and the hashed data is the concatenation:
userId + uri + signatureTimestamp
URI example: If the request is made to
https://repo-staging.sagebase.org/repo/v1/dataset?sort=name&limit=3
then the URI is:
/repo/v1/dataset
Authentication Failure
For requests that fail to be authenticated the response will include the headers:
WWW-Authenticate: authenticate Crowd
and a plain text body: "The token provided was invalid or expired."
API for Authorization
Default groups
...