SeqsLab API tokens

06/16/2021

API version v3

The OAuth 2.0 authorization code grant, as described in section 4.1 of the OAuth 2.0 specification (external link), can be used with SeqsLab client apps on a computer to gain access to SeqsLab API apps and protected resources. Using SeqsLab identity auth endpoint, which incorporates the Microsoft identity platform implementation of OAuth 2.0, you can add Azure sign-in and SeqsLab API access to your mobile and desktop apps.

The following sections describe different ways to obtain the SeqsLab API bearer token:

  1. Use your system web browser

  2. Use the SeqsLab CLI app installed on your computer

  3. Program directly against HTTP requests in your application

Important

To complete the following instructions, you must have a valid Azure AD work or school account and your account must have been granted access to the SeqsLab platform.

Use the system web browser

To obtain an API token, you need to sign in with Azure and request an authorization code for the SeqsLab API app. The authentication flow begins with the client directing you to the SeqsLab identity auth endpoint /auth/v3/signin/azure/. To begin the request flow, go to https://api.seqslab.net/auth/v3/signin/azure/ (external link).

After signing in, the browser redirects to the SeqsLab auth endpoint with an authorization code and SeqsLab responds with valid API tokens in application/json format after validating the signed-in user identity.

Below is an example of a successful API token response:

{
    "tokens": {
        "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
    }
}

Attribute

Description

tokens.refresh

Used to get new API access token over time. Refresh token lifetime is 24 hours.

tokens.access

Used to authorize the client to access SeqsLab on behalf of a user. Access token lifetime is 2 hours.

Use the API access token

You can use the API access token when sending requests to SeqsLab API apps by including it in the HTTP Authorization header:

GET /wes/v1/service-info/
Host: https://api.seqslab.net
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Refresh the API access token

API access tokens are short-lived. When they expire, you must refresh them to continue accessing SeqsLab API apps. To refresh the access token and obtain a new one, submit a POST request to the /auth/v3/token/refresh/ endpoint that provides the refresh token.

Currently, refresh tokens aren’t revoked when used to acquire new access tokens. According to the OAuth 2.0 specification, SeqsLab may issue a new refresh token in the future release, and the client must discard the old refresh token and replace it with the new refresh token.

Important

The refresh token expires after 24 hours. Client must be prepared for users to sign in again to get new API tokens every 24 hours.

POST /auth/v3/token/refresh/ HTTP/1.1
Host: https://api.seqslab.net
Content-Type: application/json

{
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Below is an example of a successful API token response:

{
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Attribute

Description

access

The new API access token

Use SeqsLab CLI app

SeqsLab CLI is an advanced user interface for interactively and automatically accessing protected SeqsLab resources using the SeqsLab API apps. The SeqsLab CLI is a Python-based command line program and can be executed in non-interactive mode that works exactly like traditional Linux-based command line utilities. In the following example, we use the CLI interactive mode to demonstrate how to obtain API tokens.

On the command line or shell prompt, launch the SeqsLab CLI with a target backend that defaults to azure using the following command:

seqslab --backend azure

When the CLI launches successfully, you will see the CLI command prompt.

Type auth sign command to sign in to SeqsLab API and obtain API tokens. With no additional command argument, the signin command uses OAuth 2.0 device code flow (external link), which allows users to sign in to a browserless system.

auth signin

The command displays a message similar to the following example.

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code S7QY5LNXW to authenticate.

Follow the instructions for authenticating against the Microsoft identity platform. When you complete the authentication process, the CLI can get API tokens as needed and it returns a normal command prompt where you can continue running other commands.

Alternatively, if the system where you run SeqsLab CLI has a web browser, you can sign in with the OAuth 2.0 authorization code flow by providing the interactive argument to auth signin command. The command will automatically pop up a web browser window and ensure that you are not presented with an interactive prompt during your single sign-on experience.

auth signin interactive=True

If you encounter the error message below, it indicates that your Azure user account is not yet registered and authorized to access SeqsLab API apps.

401 Client Error: Unauthorized for url: https://api.seqslab.net/auth/v3/signin/azure/

The SeqsLab CLI signin command will NOT prompt for consent and ask you to grant permissions to SeqsLab systems. Therefore, you must have already signed in and granted permissions using the SeqsLab management console.

After completing the sign-in process, you can get the API access token in requests to SeqsLab API apps by including it in the HTTP Authorization header.

auth token

The command automatically refreshes the access token when it expires. When tokens expire, you will need to sign back in to the SeqsLab API. The tokens are persistently cached in system-supported secret services, such as Freedesktop Secret Service and macOS Keychain. As a result, the valid access token can be used across multiple CLI sessions.

Program directly against HTTP requests

SeqsLab identity auth endpoint allows users to use existing valid id_token and access_token obtained directly from the Microsoft identity platform or a third-party open source library, and exchange these for SeqsLab API tokens. There are many ways to get required tokens using OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform. For instructions on how to write your code and choose the auth flow that is most suitable for your use case, go to the Azure Active Directory documentation (external link).

You will need to use the following SeqsLab API app parameters when constructing request data for OAuth 2.0 authorization and authentication flow:

Parameter

Value

client_id

b10403db-7700-42c2-996e-116578438579

scope

https://management.azure.com/user_impersonation https://batch.core.windows.net/user_impersonation https://storage.azure.com/user_impersonation https://graph.microsoft.com/User.Read openid profile offline_access

redirect_uri

http://localhost:{your local http server listening port}

When exchanging SeqsLab API tokens, the Azure token exchange endpoint /auth/v3/token/azure/ requires the client to send an HTTP POST request like this:

POST /auth/v3/token/azure/ HTTP/1.1
Host: https://api.seqslab.net
Content-Type: application/json

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Below is an example of a successful API token response:

{
    "tokens": {
        "refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
    }
}

Attribute

Description

tokens.refresh

Used to get new API access token over time. Refresh token lifetime is 24 hours.

tokens.access

Used to authorize the client to access SeqsLab on behalf of a user. Access token lifetime is 2 hours.