Within your authored Workflows, we inject a selection of variables and files, based on your setup. These can range from Arguments, allowing you to specify variables for use throughout your script, to files, using Assets, our feature to allow direct injection of a specified file, or even outputs from other Workflow runs, using our Dependencies feature. However, you may need to access other details on your sample(s) that we do not automatically inject, such as sample metadata. To do this, we allow you to decide whether a bearer token should be injected into your Workflow run.

A Bearer Token is a string unique to you/your session, which authorizes access to an API, usually under OAuth 2.0. It works similarly to an API key in granting you access to our API. However unlike an API key, they can be restricted in use, for instance, to a specific instance or duration.

One of the benefits of using a bearer token is that you will not have to risk exposure of your API key in a workflow or workflow run, particularly if that workflow or its results are shared with your colleagues. And for the case of One Codex Bearer Tokens, these will expire, preventing further access.

When drafting or editing a workflow, you will see a checkbox under the boxes for "Workflow Name" and "Description". This checkbox allows you to "Include temporary authentication key in ONE_CODEX_BEARER_TOKEN environment variable." The checkbox will be unchecked by default. Checking the box will allow you to use the ONE_CODEX_BEARER_TOKEN variable throughout your workflow as needed.

You can pass a bearer token directly in python using the Api() command from the One Codex python library. You can explicitly call Api(ONE_CODEX_BEARER_TOKEN). However as the ONE_CODEX_BEARER_TOKEN is an environmental variable, calling on Api() will also search for the environment variable if no API key or bearer token are explicitly passed. From there, you can use the One Codex python library as you would with an API key. Likewise for command-line API access, you may provide the ONE_CODEX_BEARER_TOKEN in lieu of your ONE_CODEX_API_KEY.

Bearer Tokens provide a layer of safety as they have an expiration date from the point of creation. However the ONE_CODEX_BEARER_TOKEN does grant you access to all of your samples and analyses, as your API key does (e.g. access to all of your samples and those that have been shared with you, along with their metadata and analyses). We encourage caution in how you use a ONE_CODEX_BEARER_TOKEN, to ensure that you explicitly use it for the correct access (e.g. the sample that you are working on, as opposed to all samples).

We also warn caution in printing your ONE_CODEX_BEARER_TOKEN in your logs or saving it to a file in the outputs. While a ONE_CODEX_BEARER_TOKEN does expire, the expiry time does have to be long enough to cover the duration of a long-running workflow. If you print or save the bearer token and share the results prior to the expiration, you may grant more access to your data than you intended to whomever you share the results with.

Learn about the other key features of developing a workflow here.