SeqsLab API tokens

SeqsLab API tokens#

2/1/2023

API version v3

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

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

Use your system web browser
Use the SeqsLab CLI app installed on your computer
Program directly against HTTP requests in your application
Program auth code flow with redirect URIs

Important

To complete the following instructions, you must have a valid Microsoft Entra ID work or school account that has been granted access to the SeqsLab platform.

Use your 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://your-site.seqslab.net/auth/v3/signin/azure/. You must replace your-site with your own domain name.

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://your-site.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 are not 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://your-site.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 the SeqsLab CLI app installed on your computer#

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. It can be executed in a 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.

Use the auth sign command to sign in to SeqsLab API and obtain API tokens. Without additional command arguments, the signin command uses the OAuth 2.0 device code flow ( external link ), which allows you 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 have completed the authentication process, the CLI can get the required API tokens and it displays a normal command prompt where you can continue running other commands.

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

auth signin interactive=True

If you encounter the error message below, this means 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 display a prompt for consent and ask you to grant permissions to SeqsLab. 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 in your application#

The 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, refer 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 email
redirect_uri	http://localhost:{your local http server listening port}/auth/

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

POST /auth/v3/token/azure/ HTTP/1.1
Host: https://your-site.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.

Program auth code flow with redirect URIs#

SeqsLab also allows a client web application to obtain SeqsLab API tokens programmatically and automatically from the OAuth 2.0 authorization code grant. This integrative mechanism provides a streamlined user sign-in experience. The authentication flow requires a user-agent (e.g., web browser) that supports redirection from the identity server (e.g., Microsoft identity platform) to the provisioned SeqsLab API app, and from the SeqsLab API app back to your application. This auth code flow also requires your application to provide an endpoint (redirect URI) that receives POST requests redirected from the SeqsLab API app after user authentication is completed.

Redirect URIs for your web application#

A redirect URI, or a reply URL, is the location where the SeqsLab authorization sends the signed-in user account information after your client web app is successfully authorized and granted an API access token. When your application sends a request to the SeqsLab identity auth endpoint /auth/v3/signin/azure/, the request is sent with a redirect URI as a query parameter. This redirect URI should match one of the URIs registered in your SeqsLab organization account.

Redirect URI registration#

To register one or more redirect URIs, you must first sign in to SeqsLab with a Global Administrator user using one of the previously described methods. However, we recommend using the SeqsLab CLI to perform the following task.

Sign in to the SeqsLab platform.
```
seqslab auth signin
```

Obtain your organization ID.

seqslab user get

This example shows a successful command response and the organization specifies your organization ID:

{
    "id": "YOUR USER ID",
    "username": "YOUR USER NAME",
    "email": "YOUR EMAIL",
    "is_active": true,
    "last_login": "2023-02-02T05:57:37.158757Z",
    "organization": "org_P7VOS8Hn6l41xxx",
    "roles": ["Global administrator"]
}

Register redirect URIs for your organization auth code flow. To register more than one URI, ensure that each URI is separated by a space when providing command arguments for --uri.
```
seqslab org redirect-uri --id "<OrganizationID>" --uri "<SomeURI> <AnotherURI>"
```
Important

Redirect URI registration is an atomic operation to ensure information integrity and correctness. This means that each time you register new URIs, all existing records will be removed.

To remove all existing redirect URIs, you can execute the command without URI command arguments.
```
seqslab org redirect-uri --id "<OrganizationID>"
```

Restrictions and limitations#

Redirect URIs	Description
Maximum length	Use a maximum of 200 characters for each redirect URI that you register to your account.
Wildcards in URIs	Wildcards are not allowed due to security restrictions. According to section 3.1.2 of RFC 6749, a redirection endpoint URI must be an absolute URI.
Query parameter support	Query parameters are allowed in redirect URIs.
Supported schemes	The HTTPS scheme (`https://`) is supported for all redirect URIs. The HTTP scheme (`http://`) is only supported for localhost URIs and should only be used during local application development and testing.

Request authentication and obtain access tokens for signing in users#

The authentication flow begins with your application directing the user to the SeqsLab identity auth endpoint /auth/v3/signin/azure/.

This is an example request for a PHP application:

<?php
session_start();

// Your registered redirect URI
$_SESSION["redirect_uri"] = 'http://localhost/myapp/';

// CSRF protection for example
$_SESSION["csrf_token"] = md5(uniqid(mt_rand(), true));

// Redirect user to auth endpoint.
header('Location: https://your-site.seqslab.net/auth/v3/signin/azure/?redirect_uri=' . $_SESSION['redirect_uri'] . '&csrf_token=' . $_SESSION['csrf_token']);
?>

Although the CSRF token is not strictly required, we recommend including a CSRF token as a best practice. As specified in section 10.12 of RFC 6749, the CSRF token can help protect you from malicious URIs. If you choose not to use a CSRF token, you may want to add the SeqsLab domain as a trusted domain in your application, wherever appropriate, to exempt CSRF validation.

After directing the user to the SeqsLab identity auth endpoint, SeqsLab incorporates the cloud identity platform (e.g., Microsoft Entra ID) to authenticate and authorize the user. Once successful, SeqsLab grants the access tokens by redirecting a POST request to the specified redirect URI. Your application can then use the tokens to access the SeqsLab platform services on behalf of the user. When the csrf_token is present, make sure that you validate for CSRF protection.

POST /myapp HTTP/1.1
Host: http://localhost
Content-Type: application/x-www-form-urlencoded

scope=user_id
&token_type=Bearer
&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...
&expires_in=7200 
&csrf_token=JqQX2PNo9bpM0uEihUPzyrh  // NOTE: Only presented when provided by your application.

Parameter	Description
scope	The unique ID of the user signing in.
token_type	The token type value. The only type that SeqsLab supports is `Bearer`.
access_token	The API access token. Your app can use this token to authenticate access to the SeqsLab platform services.
refresh_token	An OAuth 2.0 refresh token. Your app can use this token to acquire other API access tokens after the current access token expires. Refresh token lifetime is 24 hours.
expires_in	The access token validity duration (in seconds).
csrf_token	The CSRF token provided to the SeqsLab identity auth endpoint. This is only present when your application provides it at the start of the auth code flow process.

Sign out#

To sign out a user from the SeqsLab platform, you can send a POST request to the /auth/v3/signout/azure/ endpoint.

POST /auth/v3/signout/azure/ HTTP/1.1
Host: https://your-site.seqslab.net
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

SeqsLab API tokens

Contents

SeqsLab API tokens#

Use your system web browser#

Use the API access token#

Refresh the API access token#

Use the SeqsLab CLI app installed on your computer#

Program directly against HTTP requests in your application#

Program auth code flow with redirect URIs#

Redirect URIs for your web application#

Redirect URI registration#

Restrictions and limitations#

Request authentication and obtain access tokens for signing in users#

Sign out#