> For the complete documentation index, see [llms.txt](https://docs.biodock.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biodock.ai/public-api/authentication.md).

# Authentication

*What you'll get: an API key, how to send it, how to act in a workspace, and where to find the IDs the API needs.*

## Create an API key

1. Click **API keys** in the sidebar, under **Personal**, or go to [app.biodock.ai/api-keys](https://app.biodock.ai/api-keys).
2. Click **Create API key**.
3. Give the key a **Name** you'll recognise, and choose when it **Expires**: **Never**, 30, 60 or 90 days, or 1 year.
4. Click **Create**, then copy the key.

<figure><img src="https://3806122466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk3DfNQKoMy1JXdaDLvpG%2Fuploads%2Fgit-blob-3880cbe68edf016ce884136a915bbe6dba3a8d93%2Fv2-api-keys.png?alt=media" alt="The API keys page with the Create API key button and the Your keys table"><figcaption><p>The <strong>API keys</strong> page.</p></figcaption></figure>

The key is shown **only once**. Biodock stores only a hash of it, so nobody, including our support team, can show it to you again. If you lose it, create a new key and revoke the old one.

**Keep your keys secret.** A key can do anything the API offers on your behalf; there are no read-only keys. To revoke a key, click **Revoke** next to it on the **API keys** page. Revoking takes effect immediately. Give each key a different name, so you can tell them apart when you revoke one.

## Send the key

Send the key in the `X-API-KEY` header of every request. A missing or unknown key gets a `401` response with the message `Unauthorized`.

Check that a key works with this endpoint:

## Verify API key

<mark style="color:blue;">`GET`</mark> `https://app.biodock.ai/api/external/check`

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| X-API-KEY<mark style="color:red;">\*</mark> | String | API key.    |

{% tabs %}
{% tab title="200: OK Request was processed successfully" %}

```javascript
{
    user: "auth0|1234567890",
    email: "you@example.org",
    message: "API key is valid."
}
```

{% endtab %}
{% endtabs %}

```python
import requests

API_KEY = "" # Replace with your api key
URL = "https://app.biodock.ai/api/external/check"

headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

response = requests.get(URL, headers=headers)
print(response.text)
```

## Act in a workspace

API keys are personal. A key acts in your personal account, even one you created while inside a workspace.

To act in a [workspace](https://docs.biodock.ai/workspaces/workspaces.md) you're a member of, name it in the request, with either:

* the header `X-Biodock-Workspace: <workspace-url>`, or
* the query parameter `?workspace=<workspace-url>`.

`<workspace-url>` is the part of the workspace's address after `/w/`.

**Keys that moved with your team.** If Biodock moved your team into a workspace, your unexpired keys moved with it. They act in that workspace without naming it. The **API keys** page shows *"Acts in \<workspace>"* under each such key's name. To script against your new personal account, create a new key.

| Response                                                                                                                                                                         | Why                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403` *"You do not have access to this workspace."*                                                                                                                              | You named a workspace you're not an active member of, or a moved key was used after you left, were deactivated, or the workspace was archived. A moved key never falls back to your personal account. |
| `403` *"This workspace is suspended, so nobody can open it until Biodock reactivates it. Your own account is not affected. Contact <support@biodock.ai> if you have questions."* | Biodock has suspended the workspace.                                                                                                                                                                  |

## Find IDs

Several endpoints take the ID of a file, folder, pipeline or analysis job:

* **Files and folders:** on the **Files** page, each item's ID appears under its name with a **Copy ID** button. IDs show only when every column of the list is visible, so widen the window and show any hidden columns. You can also get IDs from [List filesystem items](https://docs.biodock.ai/public-api/resources/files.md).
* **Pipelines:** use [List pipelines](https://docs.biodock.ai/public-api/resources/pipelines.md). Pipeline IDs aren't shown in the app.
* **Analysis jobs:** use the `id` returned when you submit a job, or by [List analysis jobs](https://docs.biodock.ai/public-api/resources/analysis-jobs.md). Don't take it from the app's address bar: the ID in a result's URL is a different ID, and the API answers `400` *"Invalid analysis job id"*.

<figure><img src="https://3806122466-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk3DfNQKoMy1JXdaDLvpG%2Fuploads%2Fgit-blob-fca9459d507d7f1c708ebb57966642dc78ebb782%2Fdocs-api-copy-id.png?alt=media" alt="The Files page at full width, with a file&#x27;s ID shown under its name and the Copy ID button next to it"><figcaption><p>On <strong>Files</strong>, the ID and <strong>Copy ID</strong> appear under each name when every column is shown.</p></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.biodock.ai/public-api/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
