Versions Compared

Old Version 109

changes.mady.by.user Bruce Hoff

Saved on

compared with

New Version Current

changes.mady.by.user David Burdick

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Missing password or user ID already exists:

Code Block
HTTP/1.1 400401 Bad RequestUnauthorized

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

...

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

...

If the email address is not in the user database:

Code Block
HTTP/1.1 400404 BadNot Request

Note: The email template is in the auth-util package, in the file resetpasswordEmail.txt. The reset link, along with the smtp parameters, is in the file authutil.properties.

...

Found

Set Password

Code Block
POST https://auth-staging.sagebase.org/auth/v1/user/apiPasswordEmailpassword
{"emailsessionToken":"demouser@sagebase.org"}abcdefgh-0123-4567-ijkl-mnopqrstuvwx", "password":"foobar"}

Successful Response:

Code Block
HTTP/1.1 204 No Content

Get Secret Key for HMAC Authentication

Code Block
GET

...

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

Successful Response:

Code Block
HTTP/1.1 400 Bad Request200 {"secretKey":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="}

Note: The email template Session token is in the auth-util package, in the file setAPIpasswordEmail.txt. The reset link, along with the smtp parameters, is in the file authutil.properties.

Set Password

...

required in request header.  The returned key is that of the authenticated user.

Invalidate Secret Key

Code Block
DELETE https://auth-staging.sagebase.org/auth/v1/userPassword
{"email":"demouser@sagebase.org", "password":"foobar"}
secretKey

Successful Response:

Code Block
HTTP/1.1 204  No Content

Note: Session token token or HMAC signature is required in request header.

...

  The key which is invalidated is that of the authenticated user.

Initiate Session (Login)

Request:

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

Successful Response:

Code Block
HTTP/1.1 200 201 Created
Content-Type: application/json
{"secretKeysessionToken":"0Ocy/cW/3WIdZg3Up9dguO4Kh5smBKpN7iWXAvVQqekGD3gT4nc7PWwlfOhcL+KW6W4PjXtgPQNhiP7yrwjfwQ=="}

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

Invalidate Secret Key

Code Block
DELETEAYcOhWIm9NdOC6BdzzzisQ00", "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:

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

Successful Response:

Code Block
HTTP/1.1 204  No Content

Note: Session token is required in request header.  The key which is invalidated is that of the user authenticated by the session token.

Initiate Session (Login)

RequestError Response, if the session token is invalid:

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

or

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

 

Successful Response:

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

Error Response, if the user authentication details are incorrect:

Code Block
HTTP/1.1 400 Bad Request
AuthenticationURL:HTTP/1.1 401 Unauthorized
{"reason":"Session token is not valid"}

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

Code Block
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:

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

Accept the Synapse Terms of Use

Request:

Code Block
POST https://auth-staging.sagebase.org/auth/v1/session
Content-Type: application/json
{"reason":"Unable to authenticate."}

 

...

termsOfUse
{"sessionToken":"AYcOhWIm9NdOC6BdzzzisQ00", "acceptsTermsOfUse":"true"}

Response:

Code Block
HTTP/1.1 403204 Forbidden

<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
{"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 No Content

Note: The ToU are available at this URL:

Code Block
https://auth-prod.sagebase.org/auth/v1/termsOfUse.html

Authentication via OpenID

Synapse supports authentication via OpenID with Google as the identity provider.  You as a client initiate the users identity verification with Google, and pass through the URL parameters to our REST api which will unpack the openID parameters, and verify the account. If login is successful a Session object will be returned. See the Synapse Authentication REST API documentation for details. 

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

Send Change Password Email:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\"}" -X POST https://auth-staging.sagebase.org/auth/v1

...

Note: Session token is required in request header.

 

Response:

Code Block
HTTP/1.1 204 NO CONTENT

Authentication via OpenID

Synapse supports authentication via OpenID.  Specifically there is a service which performs the OpenID handshake and, upon success, logs the user into Synapse and returns a Synapse session token.  If it is the first time that the user has logged in to Synapse, then after successful OpenID authentication a new user account is created, a session is created and the session token is returned.  The basic request is:

Code Block
POST https://synapse.sagebase.org/Portal/openid?OPEN_ID_PROVIDER=<OpenIDEndpoint>&RETURN_TO_URL=<RedirectURL>

The successful response is a redirect to <RedirectURL>:<sessonToken>:

Code Block
HTTP/1.1 302 Moved Temporarily
...
Location: <RedirectURL>:<sessionToken>
...

To authenticate against Google's OpenID endpoint, the request is:

Code Block
POST https://synapse.sagebase.org/Portal/openid?OPEN_ID_PROVIDER=https%3A%2F%2Fwww.google.com%2Faccounts%2Fo8%2Fid&RETURN_TO_URL=<RedirectURL>

If successful, but if the user has not yet accepted the Synapse Terms of Use (ToU), then instead of a session token, the redirect URL contains the literal string "TermsOfUseAcceptanceRequired":

Code Block
HTTP/1.1 302 Moved Temporarily
...
Location: <RedirectURL>:TermsOfUseAcceptanceRequired
...

In this case then authentication must be repeated with explict ToU acceptance.  The client should display the ToU and request the user's acceptance.  The ToU are available at this URL:

...

/user/password/email

Login:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"password\":\"demouser-pw\"}" -X POST https://auth-staging.sagebase.org/auth/v1/session

Refresh session token:

curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X PUT https://auth-staging.sagebase.org/auth/v1/session

Logout:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X DELETE https://auth-staging.sagebase.org/auth/v1/

...

 

Once the user has accepted the ToU, the authentication request may repeated, including a new request parameter acceptsTermsOfUse=true:

 

...

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/

...

Sample commands, issued from cURL:

Create User:
curl -k repo/v1/dataset/test

Access repository services with HMAC-SHA1 signed request:
curl -i -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

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

Send Change Password Email:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\"}" -X POST https://auth-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"

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/authrepo/v1/userPasswordEmail

Login:
curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"email\":\"demouser@sagebase.org\", \"password\":\"demouser-pw\"}" -X POST https://auth-staging.sagebase.org/auth/v1/session

Refresh session token:

curl -k -H "Content-Type:application/json" -H "Accept:application/json" -d "{\"sessionToken\":\"QYNoamrOKK0dBhjZOFfbAg00\"}" -X PUT https://auth-staging.sagebase.org/auth/v1/session

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 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: "Digest" your email

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

API for Authorization

Default groups

Currently, there are two default groups that can be used to set permissions:

Group Name

Description

PUBLIC

All users belong to this group. This is the only group that the anonymous@sagebase.org user belongs to. The anonymous user is used for anyone that has not logged in to Synapse. Therefore, granting permission to PUBLIC will grant that permission to everyone including users that have not logged in.

AUTHENTICATED_USERS

All users that have logged in will automatically belong to this group. Therefore, granting permissions to AUTHENTICATED_USERS will grant that permission to any user that has logged in to Synapse.

Get the users who can be added to a resource's ACL

Code Block
GET https://repo-staging.sagebase.org/repo/v1/

...

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"

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

Currently, there are two default groups that can be used to set permissions:

Group Name

Description

PUBLIC

All users belong to this group. This is the only group that the anonymous@sagebase.org user belongs to. The anonymous user is used for anyone that has not logged in to Synapse. Therefore, granting permission to PUBLIC will grant that permission to everyone including users that have not logged in.

AUTHENTICATED_USERS

All users that have logged in will automatically belong to this group. Therefore, granting permissions to AUTHENTICATED_USERS will grant that permission to any user that has logged in to Synapse.

...

user?offset=1&limit=100
Code Block
{"totalNumberOfResults":340,
    "results":[
        {"lastName":"Bar","etag":"403","ownerId":"273956","firstName":"Foo","displayName":"Foo Bar"},
        ....
    ],
    "paging":{"next":"/repo/v1/user?offset=101&limit=100"}
}

Get the groups who can be added to a resource's ACL

Code Block
GET https://repo-staging.sagebase.org/repo/v1/userGroup
Code Block
[
  {"name":"AUTHENTICATED_USERS","id":"1","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
  {"name":"PUBLIC","id":"2","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
  {"name":"Federation Group","id":"3","creationDate":1307141423000,"uri":null,"etag":null,"individual":false}
]

Note: The "name" fields returned from /user and /userGroup are used in the "groupName" fields in the ACLs shown below.

Get Access Control List for a Resource

Returns the ACL for the node responsible for the given node's permissions. Note: In the following example, 'id' is the id of the node to which permissions are attached; there is one 'resourceAccess' entry per UserGroup (aka 'principal') having access to the resource; 'groupName' is the name of the UserGroup object; 'accessType' is the list of types of access the given UserGroup has to the given resource.

Code Block
GET https://repo-staging.sagebase.org/repo/v1/user?offset=1&limit=100/entity/{entity_id}/acl
Code Block
{"totalNumberOfResults"id":"1",
 "creationDate":3401307141851484,
  "uri":null,
 "resultsetag":[
      "0",
 {"lastNamecreatedBy":"Baradmin","etag
 "resourceAccess":[
	{"id":"4031",
	 "ownerIdgroupName":"273956PUBLIC",
	 "firstNameaccessType":["FooREAD","displayNameCHANGE_PERMISSIONS":,"Foo BarDELETE"},
        ....
  ,"UPDATE","CREATE"]
	}
 ],
    "pagingmodifiedBy":{"nextadmin":"/repo/v1/user?offset=101&limit=100"}
}

Get the groups who can be added to a resource's ACL

Code Block
GET,
 "modifiedOn":1307141851483
}

Create Access Control List for a Resource

Note: This is only used when the resource 'rid' currently inherits its access control list from an ancestor. This request causes 'rid' to cease ACL inheritance and instead use the ACL passed in with the request.

Code Block
POST https://repo-staging.sagebase.org/repo/v1/userGroup
Code Block
[
  {"name":"AUTHENTICATED_USERS","id":"1","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
  {"name":"PUBLIC","id":"2","creationDate":1307141423000,"uri":null,"etag":null,"individual":false},
  {"name":"Federation Group","id":"3","creationDate":1307141423000,"uri":null,"etag":null,"individual":false}
]

Note: The "name" fields returned from /user and /userGroup are used in the "groupName" fields in the ACLs shown below.

...

entity/{entity_id}/acl
{"id":"{entity_id}",
 "resourceAccess":[
	{"groupName":"PUBLIC",
	 "accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
	}
 ]
}

Update Access Control List for a Resource

Returns the ACL for the node responsible for the given node's permissions. Note: In the following example, 'id' is the id of the node to which permissions are attached; there is one 'resourceAccess' entry per UserGroup (aka 'principal') having access to the resource; 'groupName' is the name of the UserGroup object; 'accessType' is the list of types of access the given UserGroup has to the given resource.

...

Note: This is only used when a "entity_id" already specifies its access control list (does not inherit from an ancestor).

Code Block
PUT https://repo-staging.sagebase.org/repo/v1/entity/{entity_id}/acl
Code Block
{"id":"1",
 "creationDate":1307141851484,
 "uri":null,
 "etag":"0",
 "createdBy":"admin",
 "resourceAccess":[
	{"id":"1",
	 "groupName":"PUBLIC",
	 "accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
	}
 ],
 "modifiedBy":"admin",
 "modifiedOn":1307141851483
}

Create Access Control List for a Resource

...

","DELETE","UPDATE","CREATE"]
	}
 ],
}

Delete Access Control List for a Resource

This deletes the given object's ACL, restoring its dependence on its owner's permissions.

Code Block
DELETE https://repo-staging.sagebase.org/repo/v1/entity/{entity_id}/acl

Ask whether there is access to a Resource

Note: The query is asked for the user who is implied by the session token, or 'anonymous' if there is no token.

Code Block
GET https://repo-staging.sagebase.org/repo/v1/entity/{entity_id}/access?accessType={accessType}
Code Block
{"result":true}

API For Resource Access

The Synapse Authorization Services include support for creating abstract 'resources' and allowing users access.  The defined requests are shown below.  Note:  All requests must be authenticated, as described earlier in this document.

Authorize a User for a Resource

Code Block
POST https://repoauth-staging.sagebase.org/repoauth/v1/entity/{entity_id}/acl
{"id":"{entity_id}",
 "resourceAccess":[
	{"groupName":"PUBLIC",
	 "accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
	}
 ]
}

Update Access Control List for a Resource

Note: This is only used when a "entity_id" already specifies its access control list (does not inherit from an ancestor).

Code Block
PUT https://reporesourceAccess/{resourceName}
{"userName":"demouser@sagebase.org", "userData":"some-user-data"}

Note:  The user executing this request must be a Synapse Administrator.

Successful Response:

Code Block
HTTP/1.1 201 Created

Create a Resource-Access Session

Code Block
POST https://auth-staging.sagebase.org/repoauth/v1/entityresourceSession/{entity_idresourceName}/acl
{"id":"1",
 "etag":"0",
 "resourceAccess":[
	{"id":"1",
	 "groupName":"PUBLIC",
	 "accessType":["READ","CHANGE_PERMISSIONS","DELETE","UPDATE","CREATE"]
	}
 ],
}

Delete Access Control List for a Resource

This deletes the given object's ACL, restoring its dependence on its owner's permissions.

Code Block
DELETE https://repo

Note:  The session is created for the user authenticated in the request.

Successful Response:

Code Block
HTTP/1.1 201 Created
{"resourceAccessToken":"a1b2c3d4e5f6"}

Unsuccessful Response:

Code Block
HTTP/1.1 401 Unauthorized
{"reason": "Not authorized."}

 

Validate a Resource-Access Session

Code Block
GET https://auth-staging.sagebase.org/repoauth/v1/entity/{entity_id}/acl

Ask whether there is access to a Resource

Note: The query is asked for the user who is implied by the session token, or 'anonymous' if there is no token.

Code Block
GET https://repo-staging.sagebase.org/repo/v1/entity/{entity_id}/access?accessType={accessType}
Code Block
{"result":true}

API For Resource Access

The Synapse Authorization Services include support for creating abstract 'resources' and allowing users access.  The defined requests are shown below.  Note:  All requests must be authenticated, as described earlier in this document.

Authorize a User for a Resource

Code Block
POST https://auth-staging.sagebase.org/auth/v1/resourceAccess/{resourceName}
{"userName":"demouser@sagebase.org", "userData":"some-user-data"}

Note:  The user executing this request must be a Synapse Administrator.

Successful Response:

Code Block
HTTP/1.1 201 Created

Create a Resource-Access Session

Code Block
POST https://auth-staging.sagebase.org/auth/v1/resourceSession/{resourceName}

Note:  The session is created for the user authenticated in the request.

Successful Response:

Code Block
HTTP/1.1 201 Created
{"resourceAccessToken":"a1b2c3d4e5f6"}

Unsuccessful Response:

Code Block
HTTP/1.1 401 Unauthorized
{"reason": "Not authorized."}

 

Validate a Resource-Access Session

Code Block
GET https://auth-staging.sagebase.org/auth/v1/resourceSession/a1b2c3d4e5f6

Note:  Though the request must be authenticated, the user making the request need not be the same as the user whose session is indicated by the passed token.  This allows (for example) a 'service account' to request authentication of tokens owned by real users.

Successful Response:

Code Block
HTTP/1.1 200 OK
{"userName":"demouser@sagebase.org", "userData":"some-user-data"}

Unsuccessful Response:

Code Block
HTTP/1.1 401 Unauthorized
{"reason": "Not authorized."}

 

API for User Profiles

Get your own profile

Code Block
GETresourceSession/a1b2c3d4e5f6

Note:  Though the request must be authenticated, the user making the request need not be the same as the user whose session is indicated by the passed token.  This allows (for example) a 'service account' to request authentication of tokens owned by real users.

Successful Response:

Code Block
HTTP/1.1 200 OK
{"userName":"demouser@sagebase.org", "userData":"some-user-data"}

Unsuccessful Response:

Code Block
HTTP/1.1 401 Unauthorized
{"reason": "Not authorized."}

 

API for User Profiles

Get your own profile

Code Block
GET https://repo-staging.sagebase.org/repo/v1/userProfile

returns the profile of the authenticated user:

Code Block
{
	"firstName":"Jane",
	"lastName":"Smith",
	"userName","janesmith@sagebase.org",
	"displayName":"Jane Smith",
	"rStudioUrl":"http://rstudiohost.sagebase.org",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
}

Get another's profile

Code Block
GET https://repo-staging.sagebase.org/repo/v1/userProfile/1001

returns the profile of the specified user, where "ownerId" is the "id" field returned in the "/user" request, described above, https://sagebionetworks.jira.com/wiki/display/PLFM/Authentication+and+Authorization+API#AuthenticationandAuthorizationAPI-GettheuserswhocanbeaddedtoaresourcesACL.

Note:  Private fields (e.g. "rStudioUrl") are omitted unless the requestor is the profile owner or an administrator.

 

Code Block
{
	"firstName":"Jane",
	"lastName":"Smith",
	"displayName":"Jane Smith",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
} 


Update your own profile

Code Block
PUT https://repo-staging.sagebase.org/repo/v1/userProfile

returns the profile of the authenticated user:

Code Block
{
	"firstName":"Jane",
	"lastName":"Smith",
	"userName","janesmith@sagebase.org",
	"displayName":"Jane Smith",
	"rStudioUrl":"http://rstudiohost.sagebase.org",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
}

...

":"0"
} 

Note:  The user associated with "ownerId" must match the identity of the authenticated user making the request, otherwise and Unauthorized response will occur.

 

Update another's profile

Code Block
GETPUT https://repo-staging.sagebase.org/repo/v1/userProfile/1001

returns the profile of the specified user, where "ownerId" is the "id" field returned in the "/user" request, described above, https://sagebionetworks.jira.com/wiki/display/PLFM/Authentication+and+Authorization+API#AuthenticationandAuthorizationAPI-GettheuserswhocanbeaddedtoaresourcesACL.

Note:  Private fields (e.g. "rStudioUrl") are omitted unless the requestor is the profile owner or an administrator.

 

Code Block
{
	"firstName":"Jane",
	"lastName":"Smith",
	"displayName":"Jane Smith",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
} 

Update your own profile

Code Block
PUT https://repo-staging.sagebase.org/repo/v1/userProfile
{
	"firstName":"Jane",
	"lastName":"Smith",
	"userName","janesmith@sagebase.org",
	"displayName":"Jane Smith",
	"rStudioUrl":"http://rstudiohost.sagebase.org",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
} 

Note:  The user associated with "ownerId" must match the identity of the authenticated user making the request, otherwise and Unauthorized response will occur.

 

Update another's profile

Code Block
PUT https://repo-staging.sagebase.org/repo/v1/userProfile/1001
{
	"firstName":"Jane",
	"lastName":"Smith",
	"userName","janesmith@sagebase.org",
	"displayName":"Jane Smith",
	"rStudioUrl":"http://rstudiohost.sagebase.org",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
} 

Note:  This API is available only to administrators.

Get a batch of Headers for Users and Groups

Synapse provides a batch UserGroupHeader service to fetch information about a collection of users or groups, specified by Synapse IDs. UserGroupHeaders contain a user's name, e-mail address, display name, and picture URL, when available.

Code Block
GET https://repo-staging.sagebase.org/repo/v1/userGroupHeaders/batch?ids=1001,819

...

{
	"firstName":"Jane",
	"lastName":"Smith",
	"userName","janesmith@sagebase.org",
	"displayName":"Jane Smith",
	"rStudioUrl":"http://rstudiohost.sagebase.org",
	"ownerId":"1001",
	"uri":"/userProfile",
	"etag":"0"
} 

Note:  This API is available only to administrators.

Get a batch of Headers for Users and Groups

Synapse provides a batch UserGroupHeader service to fetch information about a collection of users or groups, specified by Synapse IDs. UserGroupHeaders contain a user's name, e-mail address, display name, and picture URL, when available.

Code Block
GET https://repo-staging.sagebase.org/repo/v1/userGroupHeaders/batch?ids=1001,819

Note that ids are specified as request parameters at the end of the URL, separated by commas. In the example above, we are fetching headers for Synapse IDs 1001 and 819.

Get Users and Groups by email

This service can be used to search for synapse users by name or email:

Code Block
GET {repo-endpoint}/userGroupHeaders?prefix=john.doe@somedomain.org

returns:

Code Block
{'totalNumberOfResults': 1,
 'children':[
    {'displayName': 'John Doe',
     'firstName': 'John',
     'lastName': 'Doe',
     'pic': {'contentType': 'image/jpeg',
             'name': '1421211.jpg',
             'tokenId': '1444862/1421211.jpg',
             'previewId': '1444863/1421211.jpg',
             'md5': '3211e11de379bc62b70bd2a1fc49255e',
             'previewState': 'PREVIEW_EXISTS'},
     'email': 'joh...e@somedomain.org',
     'ownerId': '1421212',
     'isIndividual': True}],
 'prefixFilter': 'john.doe@somedomain.org'}
 

More Examples

Add a particular user with full access and identified individuals with read-only access to a project.

...