h1. API for Authentication and Authorization
{toc}


h2. API for Authentication


h3. Create User
{code}
POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user
{"userId":"demouser", "email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User"}
{code}


Successful Response:
{code}
HTTP/1.1 201 Created
{code}


Missing password or user ID already exists:
{code}
HTTP/1.1 400 Bad Request
{code}


h3. Update User

{code}
PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user
sessionToken:<sessionToken>
{"userId":"demouser", "email":"demouser@sagebase.org", "firstName":"demo", "lastName":"user", "displayName":"Demo User"}
{code}

&nbsp;where <sessionToken> is that returned by "Initiate Session", below.

Successful Response:
{code}
HTTP/1.1 200 OK
{code}

Error Response, if the session token is missing or does not match userId:
{code}
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"reason":"Not authorized."}
{code}

h3. Send Change-Password Email
{code}
POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/userPasswordEmail
{"userId":"demouser"}
{code}


Successful Response:
{code}
HTTP/1.1 204 NO CONTENT
{code}

h3. Initiate Session (Login)

Request:

{code}
POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"userId":"demouser", "password":"demouser-pw"}
{code}


Successful Response:
{code}
HTTP/1.1 201 Created
Content-Type: application/json
{"displayName":"Demo User","sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}

Error Response, if the user authentication details are incorrect:
{code}
HTTP/1.1 400 Bad Request
AuthenticationURL: http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
Content-Type: application/json
{"reason":"Unable to authenticate."}
{code}




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



h3. Refresh Token (reset timer)

Request:

{code}
PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}


Successful Response:
{code}
HTTP/1.1 200 OK
{code}

Error Response, if the session token is invalid:
{code}
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
{code}

h3. Terminate Session (Logout)



Request:

{code}
DELETE http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}


Response:

{code}
HTTP/1.1 204 NO CONTENT
{code}



h2. Sample commands, issued from cURL:

Create User:
curl \-k \-H "Content-Type:application/json" \-H "Accept:application/json" \-d "\{\"userId\":\"NEWuser\", \"email\":\"demouser@sagebase.org\", \"firstName\":\"demo\", \"lastName\":\"user\", \"displayName\":\"Demo User\"}" \-X POST [http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user]







Update User:
curl \-k \-H "Content-Type:application/json" \-H "Accept:application/json" \-d "\{\"userId\":\"NEWuser\", \"email\":\"demouser@sagebase.org\", \"firstName\":\"NEWdemo\", \"lastName\":\"NEWuser\", \"displayName\":\"NEWDemo User\"}" \-X PUT [http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/user]


















Send Change Password Email:
curl \-k \-H "Content-Type:application/json" \-H "Accept:application/json" \-d "\{\"userId\":\"demouser\"}" \-X POST [http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/userPasswordEmail]



















Login:
curl \-k \-H "Content-Type:application/json" \-H "Accept:application/json" \-d "\{\"userId\":\"demouser\", \"password\":\"demouser-pw\"\}" \-X POST [http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session]













Refresh session token:

curl \-k \-H "Content-Type:application/json" \-H "Accept:application/json" \-d "\{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"\}" \-X PUT [http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session]


















Logout:
curl \-k \-H "Content-Type:application/json" \-H "Accept:application/json" \-d "\{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" \-X DELETE [http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session]


















Access repository services anonymously:
curl \-H Accept:application/json [http://localhost:8080/repo/v1/dataset/test]


















Access repository services with session token (obtained by logging in):
curl \-H Accept:application/json \-H sessionToken:AprxPRzpmaPm7FXzV1ik0w00 [http://localhost:8080/repo/v1/dataset/test]\\




h3. Authentication of Requests to Platform

Requests shall include a header named "sessionToken"&nbsp;whose value is that&nbsp;returned by the Initiate Session request, above.&nbsp; (The session will timeout eventually, with a nominal duration of 24 hours.)

For requests that fail to be authenticated the response will include the headers:

WWW-Authenticate: authenticate Crowd










and a plain text body:&nbsp; "The token provided was invalid or expired."

h2. API for Authorization

(Note, the URL may migrate from that of the repository services to a separate location.)

h3. Create Group
{code}
POST http://repositoryservice.sagebase.org/repo/v1/usergroup
{"name":"MyGroup"}
{code}


Note: The group's name must be unique in the system.


h3. Retrieve Groups
{code}
GET http://repositoryservice.sagebase.org/repo/v1/usergroup
{code}

h3. Retrieve Group
{code}
GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{code}

h3. Delete Group
{code}
DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{code}

h3. Update Group

(shallow properties, i.e. the group's name)
{code}
PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{"name":"OurGroup"}
{code}

h3. Get the users in the system
{code}
GET http://repositoryservice.sagebase.org/repo/v1/user
{code}
Note: This provides the {uid} values for the following requests.

h3. Add a user to the group
{code}
PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}
{code}

h3. Remove a user from the group
{code}
DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}
{code}

h3. Get all the users in a group
{code}
GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users
{code}

h3. Give a group access to a resource, specifying the allowable access types

Note: A resource is specified by its type and an identifier, unique within a type.&nbsp; Allowable types are returned by the DAOs in the 'models' package, e.g. org.sagebionetworks.repo.model.DatasetDAO.getType() returns the type for Datasets.

{code}
PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}
{"accessType":["READ","CHANGE","SHARE"]}
{code}

h3. Remove all access to a resource from a group
{code}
DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}
{code}

h3. Find out the access types a group has for a resource
{code}
GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}
{code}