Authenticating and Getting User Information

Your application will generally be started by users from within BaseSpace (see App Triggering From BaseSpace), but it's also possible that a user may access your website directly or you already have a thriving user base. Or perhaps many of your users already use BaseSpace and you'd rather not implement your own authentication system.

Summary of steps

  1. Use the OAuth v2 workflow to authenticate the user with BaseSpace and retrieve an access_token
  2. Make an API request with the access_token to get information about the logged in user

OAuth v2 workflow for authentication

One of the standard OAuth v2 flows may be used. In this case, the purpose is not to get access to any resources but to simply have the user grant your application the ability to lookup basic user information.

As part of OAuth v2, the user will authenticate into BaseSpace with their account if they're not already and then allow your application to get their basic user information. Upon successful completion of the flow, your application will have an access_token that may be used to perform API requests. Your application never gets the user's credentials.

Scope parameter for authentication

The scope parameter as part of OAuth v2 is used by an application to indicate which resources and what level of access it needs. For authentication, it can be left empty as no grants to user resource are being requested, in which case the access_token will allow access to basic user information.

Alternatively, a scope of browse global may be used if you need to see what data the user has access to.

More information on using the scope parameter for OAuth v2 is available in Using Scope.

Lookup user info

Now that the user authenticated with BaseSpace and your application has received an access_token, you'll need to make an API request to lookup the user information by calling GET:users/current

Curl example to look up user info

curl -v -H "x-access-token: {access_token}" \

If successful, you'll get a 200 Ok response

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 28 Jun 2012 14:52:37 GMT
Content-Length: 250
        "Id": "1007",
        "Email": "",
        "GravatarUrl": "...",
        "DateLastActive": "2012-08-09T15:38:18.0000000",
        "DateCreated": "2011-11-11T06:02:33.0000000",
        "HrefRuns": "v1pre3/users/1007/runs",
        "HrefProjects": "v1pre3/users/1007/projects",
        "Href": "v1pre3/users/1007",
        "Name": "Example User"
    "ResponseStatus": {},
    "Notifications": []

At this point you have enough information about the user.

Note that if this is the first time you've authenticated this user and you did not provide anything in the scope parameter when performing the OAuth v2 flow, you will not be able to see any user data other than their basic info.

This workflow gives you very limited information about the user, however if you would like to request more information please refer to Obtaining Access Tokens for more information.