...
API
...
for
...
Authentication
...
and
...
Authorization
...
| Table of Contents |
|---|
API for Authentication
Create User
| Code Block |
|---|
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 |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 201 Created
{code}
Missing password or user ID already exists:
{code} |
Missing password or user ID already exists:
| Code Block |
|---|
HTTP/1.1 400 Bad Request
{code}
h3. Update User
{code} |
Update User
| Code Block |
|---|
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}
where <sessionToken> is that returned by "Initiate |
where <sessionToken> is that returned by "Initiate Session",
...
below.
...
Successful
...
Response:
...
| Code Block |
|---|
HTTP/1.1 200 OK
{code}
|
Error
...
Response,
...
if
...
the
...
session
...
token
...
is
...
missing
...
or
...
does
...
not
...
match
...
userId:
...
| Code Block |
|---|
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"reason":"Not authorized."}
{code}
h3. Send |
Send Change-Password
...
...
| Code Block |
|---|
POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/userPasswordEmail
{"userId":"demouser"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 204 NO CONTENT
{code}
h3. Initiate Session |
Initiate Session (Login)
...
Request:
...
| Code Block |
|---|
POST http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"userId":"demouser", "password":"demouser-pw"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
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 Block |
|---|
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} |
Session token is valid for a period of time, currently set to 24 hours.
Refresh Token (reset timer)
Request:
| Code Block |
|---|
PUT http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}
Successful |
Successful Response:
...
| Code Block |
|---|
HTTP/1.1 200 OK
{code}
|
Error
...
Response,
...
if
...
the
...
session
...
token
...
is
...
invalid:
...
| Code Block |
|---|
HTTP/1.1 404 Not Found
{"reason":"Unable to validate session."}
{code}
h3. Terminate Session |
Terminate Session (Logout)
...
Request:
...
| Code Block |
|---|
DELETE http://auth-sagebase-org.elasticbeanstalk.com/auth/v1/session
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00"}
{code}
|
Response:
...
| Code Block |
|---|
HTTP/1.1 204 NO CONTENT
{code}
h2. Sample |
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
...
Authentication of Requests to Platform
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.)
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
(Note, the URL may migrate from that of the repository services to a separate location.)
Create Group
| Code Block |
|---|
POST http://repositoryservice.sagebase.org/repo/v1/usergroup
{"name":"MyGroup"}
{code}
|
Note:
...
The
...
group's
...
name
...
must
...
be
...
unique
...
in
...
the
...
system.
...
Retrieve Groups
| Code Block |
|---|
GET http://repositoryservice.sagebase.org/repo/v1/usergroup
{code}
h3. Retrieve Group
{code} |
Retrieve Group
| Code Block |
|---|
GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{code}
h3. Delete Group
{code} |
Delete Group
| Code Block |
|---|
DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{code}
h3. Update Group
|
Update Group
(shallow
...
properties,
...
i.e.
...
the
...
group's
...
name)
...
| Code Block |
|---|
PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{id}
{"name":"OurGroup"}
{code}
h3. Get the users in the system
{code} |
Get the users in the system
| Code Block |
|---|
GET http://repositoryservice.sagebase.org/repo/v1/user
{code}
|
Note:
...
This
...
provides
...
the
...
{uid}
...
values
...
for
...
the
...
following
...
requests.
...
Add
...
a
...
user
...
to
...
the
...
group
...
| Code Block |
|---|
PUT http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}
{code}
h3. Remove a user from the group
{code} |
Remove a user from the group
| Code Block |
|---|
DELETE http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/users/{uid}
{code}
h3. Get all the users in a group
{code} |
Get all the users in a group
| Code Block |
|---|
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. Allowable types are returned by the DAOs in the 'models' package, e.g. |
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. 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 Block |
|---|
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} |
Remove all access to a resource from a group
| Code Block |
|---|
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} |
Find out the access types a group has for a resource
| Code Block |
|---|
GET http://repositoryservice.sagebase.org/repo/v1/usergroup/{gid}/resources/{rtype}/{rid}
{code} |