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

# Authentication

> Sign in to Elementum, understand profiles, and select the correct organization workspace.

<Warning>
  **Limited Release.** The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you're on the latest EDK version before starting new projects.
</Warning>

The EDK separates authoring from authentication. The TypeScript SDK is credential-free and never calls the platform. The managed `elementum` toolchain owns sign-in and all authenticated platform operations.

## What a profile selects

A profile is a locally saved authentication configuration for one Elementum target. It identifies:

* The Elementum instance
* The organization
* An optional organization environment
* Credentials and any custom endpoints

Use clear names such as `acme-dev` or `acme-prod` when you work with more than one target.

## Sign in

Create a named profile:

```bash theme={null}
elementum auth login --profile <profile>
```

Follow the interactive prompts to select the instance and organization and provide the requested credentials. Do not commit client secrets, tokens, or other authentication material to the workspace.

### Create OAuth credentials

`auth login` asks for a Client ID and Client Secret from an OAuth token:

1. Open your user profile from the bottom-right corner of the Elementum platform.
2. Select **OAuth** in the left navigation.
3. Click **Create New Token**.
4. Enter a name and expiration period, then enable **API Access**, **Read Only Access**, and **Agents Execute Access**.
5. Click **Generate Token**.
6. Copy the Client ID and Client Secret into the matching terminal prompts.

<Warning>
  The Client Secret appears only when you create the token. Store it securely; if you lose it, generate a new token.
</Warning>

Confirm the saved target:

```bash theme={null}
elementum --profile <profile> auth status
```

Review the reported instance, organization, and environment before bootstrapping a workspace.

## Manage saved profiles

Use the authentication commands to inspect or change locally saved profiles:

```bash theme={null}
elementum auth list
elementum auth switch <profile>
elementum auth rename <old-name> <new-name>
elementum auth logout --profile <profile>
```

`auth switch` changes the active profile used by platform commands that do not receive an explicit profile. It does not override the workspace safety checks described below.

For a trusted non-interactive shell, `elementum auth env` prints `ELEMENTUM_*` export statements for the active profile. Because that output includes credentials, do not write it to logs, commit it, or store it as a build artifact. Prefer your CI system's secret store and workload identity where available.

## Bootstrap with an explicit profile

The first organization pull must know where to create the workspace. Run it from the package workspace with an explicit profile:

```bash theme={null}
elementum --profile <profile> pull org --data-only
```

This creates a marked organization workspace at `<instance>/<organization>/`. Enter it and converge the local setup:

```bash theme={null}
cd <instance>/<organization>
elementum init
```

Use an explicit profile whenever no organization workspace exists yet. You should also provide one when multiple saved profiles could match the same instance and organization, or when reproducibility requires a named target.

## Automatic profile selection

Inside a marked organization workspace, `plan` and `apply` read the `<instance>/<organization>` identity from the workspace path. If exactly one saved profile matches, the CLI selects it automatically:

```bash theme={null}
elementum plan
elementum apply
```

The target can be the organization root or a nested path under `apps/`, `elements/`, or an authored file. A nested target only helps the CLI find the organization root; it does not limit the deployment to that file.

If no saved profile matches, or more than one profile has the same workspace identity, the command stops and asks for an explicit profile. An explicit profile also fails if its instance or organization conflicts with the workspace path.

<Warning>
  Automatic selection is based on the marked organization workspace, not shell variables. Always resolve an ambiguous target explicitly before planning or applying.
</Warning>

## Work safely across targets

Keep each organization under its own `<instance>/<organization>` folder. Before a sensitive operation:

1. Confirm the terminal is inside the intended organization workspace.
2. Run `elementum auth status` when automatic selection is unambiguous, or check the intended named profile explicitly.
3. Review the complete EDK plan before applying.

Authentication selects the organization and environment that EDK reads or changes. It does not replace Elementum's separate cross-environment promotion workflow. See [Plan and Apply](/edk/plan-and-apply) for that boundary.