API for Authentication and Authorization

API for Authentication

Create User

POST https://auth-staging.sagebase.org/auth/v1/user
{"email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User"}

Successful Response:

HTTP/1.1 201 Created

Missing password or user ID already exists:

HTTP/1.1 401 Unauthorized

Note: As a side effect this will send an email to the given address, prompting the user to set their password.

Send Change-Password Email

POST https://auth-staging.sagebase.org/auth/v1/user/password/email
{"email":"demouser@sagebase.org"}

Successful Response:

HTTP/1.1 204 No Content

If the email address is not in the user database:

HTTP/1.1 404 Not Found

Set Password

POST https://auth-staging.sagebase.org/auth/v1/user/password
{"sessionToken":"abcdefgh-0123-4567-ijkl-mnopqrstuvwx", "password":"foobar"}

Successful Response:

HTTP/1.1 204 No Content

Get Secret Key for HMAC Authentication

GET https://auth-staging.sagebase.org/auth/v1/secretKey

Successful Response:

HTTP/1.1 200 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="}

Note: Session token is required in request header. The returned key is that of the authenticated user.

Invalidate Secret Key

DELETE https://auth-staging.sagebase.org/auth/v1/secretKey

Successful Response:

HTTP/1.1 204  No Content

Note: Session token or HMAC signature is required in request header. The key which is invalidated is that of the authenticated user.

Initiate Session (Login)

Request:

POST https://auth-staging.sagebase.org/auth/v1/session
{"email":"demouser@sagebase.org", "password":"demouser-pw"}

Successful Response:

HTTP/1.1 201 Created
Content-Type: application/json
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00", "acceptsTermsOfUse":"true"}

Note: If the "acceptsTermsOfUse" field is "false", then an additional call to accept the Synapse terms of use is required before the session token can be used for authenticated requests

Session token is valid for a period of time, currently set to 24 hours.

Refresh Token (reset timer)

Request:

PUT https://auth-staging.sagebase.org/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}

Successful Response:

HTTP/1.1 204 No Content

Error Response, if the session token is invalid:

HTTP/1.1 401 Unauthorized
{"reason":"Session token is not valid"}

Error Response, if the user has not signed the terms of use yet:

HTTP/1.1 403 Forbidden
{"reason":"Terms of use must be signed"}

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:

DELETE https://auth-staging.sagebase.org/auth/v1/session

Note: Session token is required in request header.

Response:

HTTP/1.1 204 No Content

Accept the Synapse Terms of Use

Request:

POST https://auth-staging.sagebase.org/auth/v1/termsOfUse
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00", "acceptsTermsOfUse":"true"}

Response:

HTTP/1.1 204 No Content