Obtaining Access Tokens

In almost all cases, an app will use the App Triggering workflow to obtain an access_token, however an app can manually direct a user to the OAuth dialog to request permission to access user data. After an app had been triggered, it may need more permission to a user's data to perform an action, in this case the following workflow should be used to obtain a new access_token.

OAuth is the process of obtaining access to a user's data. In BaseSpace, there exist a few ways to get this access to user data, they will be described in detail.

In brief, when an application is triggered in BaseSpace, the workflow is:

  • Your application redirects the user to the BaseSpace authorization dialog with a scope of access specified
  • The user will login if not logged in already and either grant access to your application or cancel
  • BaseSpace redirects the user to your application with either an authorization code or an indication that the user canceled
  • Your application makes a web request directly to the API with the authorization code. The API responds with an access token
  • After this process is complete, your application includes the access token in all API requests to BaseSpace on that user's behalf.

Currently the BaseSpace API supports two OAuth v2 flows which are described on this page. The first is best suited for web applications and the second for just about any other scenario.

OAuth flow for web-based apps

Use this flow if you host a web application and the user accesses it via a browser.

Summary for web-based apps

  • Open the BaseSpace authorization dialog in the user's browser with a list of rights that the app needs to be provided.
  • User accepts or rejects the access request and is redirected back to the app. If access was granted, an authorization_code is provided.
  • Exchange the authorization_code for an access_token by making a direct call to the API.

Getting the authorization code

Direct the user to our OAuth dialog located at:

https://basespace.illumina.com/oauth/authorize?client_id={YOURCLIENTID}&redirect_uri={YOURREDIRECTURI}&response_type=code&scope={SCOPEREQUESTED}

with the following query parameters:

  • client_id (required): available in the application management screen
  • redirect_uri (required): the URL to your server that the user’s browser will be redirected to once authorization is completed. This must match the URL you provided when creating the application. If the hostname is localhost then the schema and port number do not have to match the registered value. This allows your desktop app to listen on a local port for the browser redirect to complete the flow.
  • response_type (required): Must be the value code
  • scope (optional): the set of permissions and resources being requested. Refer to BaseSpace Permissions.
  • state (optional): an opaque value that will be passed back to your redirect_uri

If the user is already logged in, we validate the login cookie that we have stored on the user’s browser, authenticating the user. If the user is not logged in, they are prompted to enter their credentials. Once authenticated, the OAuth dialog will prompt the user to authorize the app.

If the user chooses to cancel, we’ll issue a redirect (via HTTP 302 status code) to the redirect_uri you specified like this:

https://YOUR_REDIRECT_URL?error=access_denied&error_description=The+user+did+not+allow+the+grant&state={optional state}

Otherwise if the user does wish to grant your application rights you requested, we’ll redirect to your redirect_uri like this:

https://YOUR_REDIRECT_URL?code={authorization code}&state={optional state}

In addition to the code and state, an additional parameter of appsessionuri may also be passed to you. This value specifies the context from which the user launched your app from BaseSpace, giving the application more information about the user as well. This process is described in more detail in the App Triggering guide.

Getting the access token for web-based apps

Once you have the authorization_code, you’ll need to exchange it for an access_token by performing a POST to our API at:

https://api.basespace.illumina.com/v1pre3/oauthv2/token

This request must be authenticated with your client_id and client_secret that are available in the application management screen for your app. You may provide these credentials encoded via the standard Authorization header or in the body (but not both).

The request should have the standard content-type of application/x-www-form-urlencoded used for form POSTs.

Include the following parameters:

  • code (required): The authorization_code from the previous step.
  • redirect_uri (required): The redirect_uri for the application that you’ve provided in the previous step.
  • grant_type (required): Must be the value authorization_code
  • client_id: If not using the Authorization header
  • client_secret: If not using the Authorization header

Example curl request using the Authorization header approach:

curl -v -u {YOUR CLIENT_ID}:{YOUR CLIENT_SECRET} \
-d "code={YOUR AUTHORIZATION CODE}" \
-d "redirect_uri={YOUR REDIRECT_URI}" \
-d "grant_type=authorization_code" \
https://api.basespace.illumina.com/v1pre3/oauthv2/token

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 07 Mar 2012 14:50:42 GMT
Content-Length: 105

{
    "access_token":"{YOUR ACCESS TOKEN}"
}

If you get a status code 200 response, the JSON document will include your access_token. Otherwise, the response will include an error_code and an error_description to help you figure out the problem.

OAuth flow for non-Web based applications

Unlike OAuth for web apps above, this flow doesn't require a redirect back to your application. Instead, it relies on a simple 'out-of-band' approach of the user using a browser of their choice to open a special URL in order to grant access.

Summary for non web-based apps

  • Perform an API call with the scope and your client_id to start the flow. The response will include a device_code along with a BaseSpace URI and a short code that you can display to the user.
  • Your app eithers opens a browser window to the URI or the user opens it themselves. The user will see what rights were requested and may accept or reject it.
  • Your application makes repeated calls to the API with the device_code until it gets a response indicating that the user accepted or rejected the access grant. If the grant is accepted, an access_token is returned.

Getting the verification code and device code

Start the flow by making a direct request to the BaseSpace API using POST. The request should have the standard content-type of application/x-www-form-urlencoded used for form POSTs. The URI for this request is:

https://api.basespace.illumina.com/v1pre3/oauthv2/deviceauthorization?client_id={YOURCLIENTID}&response_type=device_code&scope={SCOPEREQUESTED}

Include the following parameters:

  • client_id (required): available in the application management screen
  • response_type (required): must be the value device_code
  • scope (optional): the set of permissions and resources being requested. Refer to BaseSpace Permissions.

Example curl request:

curl -v \
-X POST \
-d "response_type=device_code" \
-d "client_id={YOUR CLIENT ID}" \ 
-d "scope=browse global" \
https://api.basespace.illumina.com/v1pre3/oauthv2/deviceauthorization

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 28 Jun 2012 14:52:37 GMT
Content-Length: 250

{
    "verification_uri":"https://basespace.illumina.com/oauth/device",
    "verification_with_code_uri":"https://basespace.illumina.com/oauth/device?code=b9bac",
    "user_code":"b9bac",
    "expires_in":1800,
    "device_code":"dd0e45ebc98c440cb8e369a85be0344a",
    "interval":1
}

Here are the fields explained:

  • verification_uri: This URI is to be displayed to the user for performing the access grant. There, the user will type the user_code.
  • verification_with_code_uri: If your app is able to open a browser window automatically, this URI may be used. It's same as above except it eliminates the need for the user to type in a code.
  • user_code: This code may be given to the user to type in manually into the verification_uri above.
  • expires_in: This is the time in seconds during which the full flow must complete.
  • device_code: This code is used for the next step of retrieving an access_token. There's no need to share this with the user.
  • interval: This is the minimum time to pause between polling requests in the next step.

Getting the access token for non web-based apps

  1. Open the browser to the verification_with_code_uri or instruct the user to open the browser and go to the URI in verification_uri and type in the user_code

  2. Begin polling for the access_token by performing API POST requests with an interval no shorter than the interval provided in the previous response to:

    https://api.basespace.illumina.com/v1pre3/oauthv2/token

Include the following parameters:

  • client_id (required): available in the application management screen.
  • client_secret (required): available in the application management screen.
  • grant_type (required): must be the value device.
  • code (required): The value of device_code in the previous response.

Example curl request:

curl -v \
-X POST \
-d "client_id={YOUR CLIENT ID}" \ 
-d "client_secret={YOUR CLIENT SECRET}" \ 
-d "code=dd0e45ebc98c440cb8e369a85be0344a" \
-d "grant_type=device" \
https://api.basespace.illumina.com/v1pre3/oauthv2/token

Response with the user not yet finishing the access grant:

HTTP/1.1 400 BadRequest
Content-Type: application/json
Date: Thu, 28 Jun 2012 15:22:59 GMT
Content-Length: 115

{
    "error":"authorization_pending",
    "error_description":"User has not yet approved the access request"
}

Response with the user rejecting the access grant:

HTTP/1.1 400 BadRequest
Content-Type: application/json
Date: Thu, 28 Jun 2012 15:22:59 GMT
Content-Length: 115

{
    "error":"access_denied",
    "error_description":"User has denied the access request"
}

Response with the user accepting the access grant:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 28 Jun 2012 14:52:37 GMT
Content-Length: 250

{
    "access_token":"{YOUR ACCESS TOKEN}"
}

Using the Access Token

Now that a user has granted your application some rights, you may make requests to the API with the access_token. For more information about using the access_token with API requests, please refer to "Using the Access Token" in the API Reference.