# Setting up applications (/docs/pentest/applications)



An application is what Trace tests. Every pentest is scoped to one or more of them, so this is where you tell Trace what your product is, where its code lives, where it runs, and how to sign in. Organization admins set up applications from **Applications** in the dashboard or with the [CLI](/docs/cli/overview).

1. Decide what to create [#1-decide-what-to-create]

Create one application for each product your customers use. Count products, not repositories or services: a web app and the API behind it are one application, and so is a product built from twenty microservices. Staging and production are two environments of the same application.

You need a second application when you have a second product with its own users and login. A customer portal and an internal admin tool are two applications. So are a web app and a mobile app, even when they share an API; link the API's repository to both.

Then pick a type for each one.

| Type            | Choose it for                                                 |
| --------------- | ------------------------------------------------------------- |
| **Web**         | Anything people use in a browser, including the API behind it |
| **API service** | An API with no frontend, such as a public or partner API      |
| **Mobile**      | An Android or iOS app                                         |
| **Desktop**     | An app people install on macOS, Windows, or Linux             |
| **CLI**         | A command-line tool your customers run                        |

If your product has a frontend, choose Web, and Trace tests the API as part of it. Choose API service only when there's no frontend at all.

How many applications an engagement includes depends on your plan. See [Pricing](/pricing).

2. Create the application [#2-create-the-application]

<DashboardAction to="applications" label="Create an application" description="Name it, pick its type, and finish setup on the next page." />

Give the application a name and a type. Web and API service applications also need the URL people use to reach them.

The other fields are optional but worth filling in. A documentation or help center URL shows Trace how your product is meant to work, which helps it tell a bug from intended behavior. Use **Notes** for anything else Trace should know, like install steps or test-mode flags. Keep secrets out of notes and add them as credentials instead.

3. Link its repositories [#3-link-its-repositories]

Link every repository that handles a request for this application: the frontend, the backend, any auth service, and background jobs that touch user data. Trace only finds bugs in code it can read, so if you're unsure about a repository, link it. You can skip marketing sites and internal tools the application never calls.

For each repository you can set a role, like Frontend or Backend API, and for a monorepo, the folder the application lives in, like `apps/web`. Turn off **Include in pentest scans** to keep a repository linked without Trace reading it. The same repository can be linked to more than one application.

Repositories come from [GitHub](/docs/integrations/github) or [Bitbucket](/docs/integrations/bitbucket). If your code lives somewhere else, use **Upload code** to add a ZIP or a folder, then link it the same way once its safety checks pass.

4. Add an environment [#4-add-an-environment]

An environment is a running copy of the application. Trace signs in, creates data, and tries real exploits against it, so use staging or a test environment if you have one.

For Web and API service applications, set the **Target URL** Trace should test, and list any other hosts that belong to it, like your API or an admin app, under **Additional URLs**.

Your first environment is named `production` and marked **Production** by default. If it's actually staging, rename it and turn **Production** off so your report describes it correctly.

Mobile, desktop, and CLI applications don't need a URL. Add an environment anyway if Trace needs to sign in to test them, since that's where credentials go.

5. Add credentials [#5-add-credentials]

Without credentials, Trace can only test what a stranger can reach. Give it accounts in at least two tenants, with more than one role in each, such as an admin and a regular member. That's how Trace checks whether one customer can see another's data, or whether a regular user can reach something only an admin is supposed to.

Most apps need a username and password, or a passwordless email login for magic links and one-time codes. APIs usually need an API key, a bearer token, or a JWT. If your app sits behind SSO, give Trace a cookie or a captured session state instead. Trace also accepts SSH private keys for hosts it should connect to, and passphrases for secrets that aren't sent with a web request.

If an account needs an email address Trace can read, for signing up, confirming the account, or receiving magic links and one-time codes, choose **Provision email** while adding the login. Trace creates an inbox and reads it during the pentest. If an account uses an authenticator app, add its setup key under **Two-factor authentication** on the saved credential. If your app asks for a passkey, Trace creates one and lists it under **Passkeys**.

Credentials are encrypted when you save them. Only organization admins can reveal a secret, and session state and SSH keys can't be revealed at all. See [How Trace handles your data](/docs/security/data-handling).

6. Upload a build [#6-upload-a-build]

For a mobile app, upload an `.apk` or `.ipa` under **Builds** on the application's page, or with [`tracecli upload build`](/docs/cli/overview#tracecli-upload-build-file---app-applicationid). Trace tests Android builds on Android emulators. For iOS, talk to the Trace team about how your app will be tested.

Desktop apps don't have a build upload yet. Say in **Notes** where Trace can download the installer, and add a credential if the download needs a login.

Greybox and blackbox tests [#greybox-and-blackbox-tests]

In a [greybox or blackbox engagement](/docs/pentest/overview#whitebox-greybox-or-blackbox), Trace doesn't read your source, so skip step 3. For greybox, add credentials as usual. For blackbox, leave them out, since Trace tests the way an outside attacker would, with no inside knowledge.