> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/build/testdrive/credentials-and-sign-in.md).

# Credentials & Sign-In

Give TestDrive an identity to run as — sign-in, bearer token, or API key — and let it learn the login once

Most of what's worth testing sits behind a login. A **credential** is one identity this workspace can run as, and a test names the credential it should use.

{% hint style="info" %}
**Use a dedicated test account.** TestDrive will click the buttons a real user clicks, including the destructive ones a test asks for. Give it an account whose data you don't mind it exercising.
{% endhint %}

## Credential Kinds

| Kind             | Use it when                           | What you provide                                                        |
| ---------------- | ------------------------------------- | ----------------------------------------------------------------------- |
| **Sign-in**      | The app has a login form              | Username and password. TestDrive learns the sign-in once and replays it |
| **Bearer token** | The app or API accepts a bearer token | A token, sent as `Authorization: Bearer …`, with no sign-in step        |
| **API key**      | The API expects a key                 | A key, sent as a header (`X-API-Key` by default) or a query parameter   |

Secrets are stored write-only. TestDrive will tell you which keys a credential holds; it will never hand the values back.

## Learned Sign-In

The first authenticated run figures out *how* this application is signed into — where the fields are, what the submit does, what "signed in" looks like. That's recorded once at the workspace level and replayed for every credential afterwards, so the second run doesn't rediscover the login page.

The **Learned sign-in** section of the Credentials tab shows either the date it was learned or **"Not learned yet — the first authenticated run will work it out."**

| Action                           | Effect                                                                      |
| -------------------------------- | --------------------------------------------------------------------------- |
| **Clear** learned sign-in        | Drops the learned flow *and* every cached session. The next run relearns it |
| **Clear** a credential's session | Drops just that identity's cached session, leaving the learned flow alone   |

Clear the learned sign-in after you change your login page; clear a single session when one account's state has gone stale.

## Choosing a Credential for a Test

Each test picks one, including **"No authentication — runs signed out"** — which is the right answer for a marketing page, a public API, or a test that's specifically about what an anonymous visitor sees.

A test that drives the interface and a test that issues HTTP requests want different things from a credential: the first needs something it can sign in with, the second needs something it can send on a request.

## Who Can Manage Credentials

Adding, editing, and clearing credentials requires update permission on the workspace. Credential names must be unique within a workspace, which keeps "which one did that run use?" answerable from the run report.

## Next Steps

| Goal                                  | Documentation                                                            |
| ------------------------------------- | ------------------------------------------------------------------------ |
| Point the workspace at an environment | [Workspaces & Application URLs](/build/testdrive/workspaces-and-urls.md) |
| Write a test that uses this identity  | [Tests & Scripts](/build/testdrive/tests-and-scripts.md)                 |
| See what a run did                    | [Results & Evidence](/build/testdrive/results-and-evidence.md)           |


---

# 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.darcyiq.com/build/testdrive/credentials-and-sign-in.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.