> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinkplatform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management.
> Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions.
> Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome.
> Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements.

# Authentication

> Choose a sign-in method, save a connection profile, and verify your identity and project context.

Connect `tp` to the ThinkPlatform deployment you use, then verify the account and project before working with resources. Start with the [installation guide](https://docs.thinkplatform.ai/cli/get-started/installation.md) if `tp --help` is not available yet.

## Set up a profile

For a person at a terminal, start with:

```bash theme={"system"}
tp profile setup
```

The wizard asks for a profile name, service URL, API audience and authentication mode. Review the defaults, complete sign-in, choose an accessible organization and project by number, and confirm the summary. Names are shown alongside IDs for disambiguation; you do not need to find IDs beforehand. Setup saves and activates the named profile only after confirmation.

```bash theme={"system"}
tp context show
tp canvas pages list
```

Cancelling, an empty access list, or an authentication/API error leaves the saved configuration and active profile unchanged. Discovery uses reads and does not create or change service resources. Sign-in can still use the existing secure credential cache described below.

Setup requires interactive input and output terminals. It rejects JSON output and root `--query` before authentication or network access. Agents and unattended scripts should use prepared profiles or the [manual context commands](https://docs.thinkplatform.ai/cli/guides/context.md#manual-selection-for-scripts), with `configure --no-prompt` when saving explicit settings. `configure` remains available for offline connection setup.

## Get your connection settings

For the production service, `tp profile setup` guides browser sign-in and project selection. If your profile is already configured, use `tp auth login` to sign in again. The shared registration is already configured, so you do not need to create an app or provide a secret. Your organization may require administrator consent. If an approval request appears, follow your organization's approval process and retry sign-in after it is approved.

> [accordion] Built-in application settings
>
> | Setting | Production value |
> | - | - |
> | Service URL | `https://thinkplatform.ai` |
> | API audience | `api://04d6aecc-4540-463a-87e3-4024ffad7428` |
> | Authentication | `interactive-browser` |
> | Tenant ID | `5a959e94-a278-467d-ab33-d59909a75bad` |
> | CLI application ID | `709439d2-4a99-44c2-8c35-9b1e71cc2e34` |
>
> These shared public-client defaults apply when the effective URL and audience match the production values and browser or device-code auth is selected. Environment variables and explicit CLI options can override them. If another URL or audience is configured without an explicit auth mode, the CLI uses `azure-cli`. Use the URL, audience, client ID, tenant, and auth mode approved for a custom deployment.

The `https://thinkplatform.example` and `api://YOUR_API` values below are placeholders for a custom deployment. Replace them with its actual settings.

## Choose an authentication mode

| Mode | When to use it | What it needs |
| - | - | - |
| `azure-cli` | Your local Azure CLI already has the intended account signed in. | Azure CLI installed and signed in, plus the API audience. |
| `device-code` | You want to complete sign-in using a code in a browser, including on another device. | For production defaults, the shared CLI registration is selected automatically; for other services, use the deployment-approved client ID, tenant and API audience. |
| `interactive-browser` | You want browser-based sign-in from your local machine. This is the default when no connection settings are configured. | For production defaults, the shared CLI registration is selected automatically; for other services, use the deployment-approved client ID, tenant and API audience. |
| `workspace-delegation` | You are inside a provisioned managed Agent Workspace. | The workspace's managed identity, injected assertion and workspace locator, API URL, and required organization/project context. |

The deployment must allow the application identity used by your chosen mode. Browser and device-code sign-in need an approved public-client registration; a web-only application registration is not sufficient. Administrator consent for one API audience does not grant access to a different API audience.

For `azure-cli`, sign in through Azure CLI as directed by your administrator before running `tp auth login`. This mode uses Azure CLI's application identity rather than the shared ThinkPlatform CLI registration, so the deployment must explicitly allow Azure CLI. For workspace delegation, use the settings injected by the workspace rather than copying credentials from another session.

## Sign in separately or use a custom deployment

**1. Set application settings for browser or device-code sign-in**

Skip this step for the production defaults. For a custom deployment, use the approved public-client ID and tenant. You can also set `THINKPLATFORM_AZURE_CLIENT_ID` and `THINKPLATFORM_AZURE_TENANT_ID` to override the production registration. These environment settings are non-secret and are not stored in profiles.

**Bash**

```bash theme={"system"}
export THINKPLATFORM_AZURE_CLIENT_ID="YOUR_CLIENT_ID"
export THINKPLATFORM_AZURE_TENANT_ID="YOUR_TENANT_ID"
export THINKPLATFORM_API_AUDIENCE="api://YOUR_API"
```

**PowerShell**

```powershell theme={"system"}
$env:THINKPLATFORM_AZURE_CLIENT_ID = "YOUR_CLIENT_ID"
$env:THINKPLATFORM_AZURE_TENANT_ID = "YOUR_TENANT_ID"
$env:THINKPLATFORM_API_AUDIENCE = "api://YOUR_API"
```

For custom deployments, set the API audience for the target service separately from the client ID used to sign in. Never use a client secret with these public-client flows.

**2. Log in and save your connection defaults**

For the production defaults, sign in using your active profile:

```bash theme={"system"}
tp auth login
```

For a custom deployment, supply its URL and audience explicitly. Put global options before the command:

```bash theme={"system"}
tp --base-url https://thinkplatform.example --audience api://YOUR_API --auth-mode interactive-browser auth login
```

Choose `device-code` or `azure-cli` as the `--auth-mode` value when appropriate. Complete any sign-in prompts yourself. Login acquires a credential, calls the service to check your identity, and saves effective connection and context settings to the selected profile after success. For production browser/device flows, it also stores an encrypted token cache in the operating system's credential store and a separate non-secret account record locally. Later CLI processes reuse that account silently while the stored credential remains valid; Azure may request sign-in again when required.

**3. Verify the account and effective context**

```bash theme={"system"}
tp auth whoami
tp context show
```

`auth whoami` makes an authenticated request to the service. Confirm it shows the intended account. `context show` displays effective local settings; it does not prove that you can access the selected project. Follow [Select a context](https://docs.thinkplatform.ai/cli/guides/context.md) to discover organizations and projects and choose one you can access.

## Configure without signing in

`configure` saves defaults without authenticating. Run it interactively to review the selected profile's settings:

```bash theme={"system"}
tp configure
```

To save connection settings without prompts:

```bash theme={"system"}
tp --base-url https://thinkplatform.example --audience api://YOUR_API --auth-mode azure-cli configure --no-prompt
tp auth login
```

`configure --reset-context` clears saved organization/project defaults when writing configuration. Review the effective context again before continuing.

## Work with profiles

Profiles keep connection and default context settings for different environments. Configuration is written to `~/.config/thinkplatform/config.json`, unless `THINKPLATFORM_CONFIG_PATH` selects another file.

```bash theme={"system"}
tp profile list
tp profile show work
tp profile use work
tp context show
```

`profile use` changes the active saved profile. Successful profile setup, login and configuration also make their selected profile active. A profile is a set of settings; switching it does not sign out of Azure or revoke a credential.

Profile selection uses `--profile`, then `THINKPLATFORM_PROFILE`, then the active saved profile (or `default`). Switching profiles changes connection settings; it does not switch the signed-in Azure account. Individual settings use explicit global flags first, environment variables second, and the selected profile third:

| Setting | Flag | Environment variables, in precedence order |
| - | - | - |
| API URL | `--base-url` | `THINKPLATFORM_API_BASE_URL`, `THINKPLATFORM_BASE_URL` |
| API audience | `--audience` | `THINKPLATFORM_API_AUDIENCE`, `AZURE_API_AUDIENCE` |
| Authentication mode | `--auth-mode` | `THINKPLATFORM_AUTH_MODE` |
| Organization | `--org-id` | `THINKPLATFORM_ORG_ID` |
| Project | `--project-id` | `THINKPLATFORM_PROJECT_ID` |

With no deployment configured, the CLI uses its production service URL and audience defaults. If you configure another URL or audience, provide the matching deployment settings; an unspecified auth mode then resolves to `azure-cli`. Workspace delegation requires an explicit, environment-provided, or profile API URL. Environment overrides can remain effective after switching profiles, so check `context show` whenever you change environments.

## Hand sign-in back to a person

When an agent reaches an interactive sign-in prompt, have a person complete it through the normal browser or device-code flow. Resume the task after checking `auth whoami` and the intended context. Do not paste passwords, access tokens, workspace assertions, or credential files into prompts or documentation.

The Python SDK can use the same credential modes. See [SDK authentication](https://docs.thinkplatform.ai/python-sdk/authentication.md) and the [authentication command reference](https://docs.thinkplatform.ai/cli/reference/commands.md#authentication).

## Secure credential persistence

CLI profiles store connection and context settings, not access tokens. Production browser/device credentials use an encrypted operating-system token cache and a separate non-secret account record at `~/.config/thinkplatform/auth/thinkplatform-cli-{hash}.json`, where `hash` is the SHA-256 of the lowercase tenant ID, a colon, and the lowercase client ID. The CLI never stores tokens in plaintext. Removing this account record removes metadata only; it does not revoke or clear the cached session in the operating system's credential store. Treat identity output as account information and review it before sharing logs.

Production browser and device-code authentication requires OS-backed encrypted credential storage. The CLI fails closed when that storage is unavailable and does not write tokens in plaintext. On headless Linux systems without Secret Service, use Azure CLI authentication if your deployment allows Azure CLI:

```bash theme={"system"}
az login --tenant 5a959e94-a278-467d-ab33-d59909a75bad
tp --auth-mode azure-cli auth login
```

## Troubleshooting

> [accordion] Browser or device-code sign-in reports a missing client ID
>
> For the production URL and audience, the shared registration is selected automatically unless client or tenant environment variables override it. For a custom deployment, set `THINKPLATFORM_AZURE_CLIENT_ID` and `THINKPLATFORM_AZURE_TENANT_ID` to its approved values. `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` are accepted as fallbacks. Confirm custom deployment settings with its administrator before retrying.

> [accordion] Sign-in cannot use secure token storage on Linux
>
> The production browser and device-code flows need Linux Secret Service for encrypted token storage. On a headless system without it, use `az login` and `--auth-mode azure-cli` if your deployment allows Azure CLI, as described above. The CLI does not fall back to storing tokens in plaintext.

> [accordion] macOS asks Python for Keychain access
>
> macOS may ask the Python interpreter running `tp` to access the login Keychain for the `ThinkPlatform CLI` encrypted token cache. **Allow** grants access for the current request, so the prompt may appear again. **Always Allow** is optional; choose it only if you recognize and trust that exact Python interpreter. Changing or upgrading the interpreter can trigger another prompt. Your Keychain password stays on your Mac; never share it in chat.
>
> If access is denied or the Keychain is locked, sign-in fails and the CLI does not store tokens in plaintext. Managed Agent Workspace managed-identity sign-in does not use your local user Keychain. Older `Microsoft.Developer.IdentityService` items are not read, migrated, or deleted by this CLI flow.

> [accordion] The account, service, or project is unexpected
>
> Inspect `tp profile show` and `tp context show`, then check environment overrides and any explicit global flags. For Azure CLI mode, confirm the account selected in Azure CLI. Run `tp auth whoami` again against the intended service, then select an accessible project using the context guide.

> [accordion] Workspace delegation cannot acquire a credential
>
> Confirm you are in the provisioned workspace with its expected API URL and context. Missing or expired assertions, missing workspace settings, managed identity configuration, or unavailable permissions need attention from the workspace administrator. Do not substitute credentials from another workspace.

> [accordion] Sign-in succeeds but an operation is denied
>
> Authentication identifies the caller; access still depends on the service's permissions and selected organization/project. Confirm the account and context, then ask your administrator for the access required by the specific operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.