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

# Deploy Keys

> Authenticate gateways with Ultra Hub without browser-based login

Deploy keys allow Ultra gateways to authenticate with Ultra Hub without requiring a user to log in through a browser. This enables headless deployment scenarios like [MDM fleet deployment](/installation/mdm-deployment), CI/CD pipelines, and server environments.

## How Deploy Keys Work

A deploy key is a long-lived API token (prefixed with `dk_`) scoped to a specific workspace. When a gateway uses a deploy key, it:

1. Authenticates with Ultra Hub using the key instead of a browser login
2. Automatically links to the workspace the key is scoped to -- this happens during `ultra install --all` (for MDM deployments) or at `ultra start` time
3. Begins syncing policies, reporting telemetry, and enforcing guardrails

Deploy keys are created by Owners or Admins in the Hub dashboard and can be distributed via MDM configuration profiles, environment variables, or other secure configuration management tools.

## Creating a Deploy Key

Navigate to **Settings > Security** in the Ultra Hub dashboard. In the **Deploy Keys** section:

1. Enter a key name (e.g., "CI/CD pipeline", "Engineering fleet")
2. Select the **workspace** the key should be scoped to
3. Choose an **expiry** option (or select "No expiry" for permanent keys)
4. Click **Create Key**

The key is displayed once after creation. **Copy it immediately** -- it cannot be retrieved later.

The key starts with `dk_` and looks like:

```
dk_e679a4b22306f684da3bf0cfd8a0833f...
```

## Using a Deploy Key

### Environment Variable

Set the `ULTRA_DEPLOY_KEY` environment variable before starting Ultra:

```bash theme={null}
ULTRA_DEPLOY_KEY=dk_your_key_here ultra start
```

### Config File

Add the key to your Ultra config file (`~/.config/ultra/config.yaml`):

```yaml theme={null}
hub:
  deploy_key: "dk_your_key_here"
```

The environment variable takes priority over the config file value.

### Managed Preferences (MDM)

For fleet deployments, set the `DeployKey` managed preference via your MDM solution:

| Key         | Value    | Domain                     |
| ----------- | -------- | -------------------------- |
| `DeployKey` | `dk_...` | `com.ultra-security.ultra` |

See the [MDM Deployment Guide](/installation/mdm-deployment) for the full setup.

## Managing Deploy Keys

The deploy keys table in **Settings > Security** shows all keys with their name, workspace, creation date, last used date, and expiry. Click **Revoke** to immediately invalidate a key.

<Warning>
  Revoking a deploy key disconnects all gateways that rely on it for authentication. Those gateways will need to re-authenticate using a new key or browser login.
</Warning>

## Identity Resolution

Deploy keys authenticate the gateway itself, but they don't identify the user behind the device. To attribute gateways to specific employees, combine deploy keys with [SCIM directory sync](/hub/scim):

1. Set `UserEmail` in managed preferences (populated by your MDM with the device owner's email)
2. Ultra sends this email to Hub during gateway link and on every heartbeat
3. Hub matches the email against the SCIM-provisioned user directory
4. The gateway is attributed to that user for audit, policy, and RBAC

See [Identity Resolution](/installation/mdm-deployment#identity-resolution) in the MDM Deployment Guide for details.

## Security Considerations

* **Treat deploy keys like passwords** -- store them in secure configuration management, not in source code
* **Scope keys narrowly** -- create separate keys per workspace or deployment group
* **Set expiry dates** -- for time-limited deployments, use expiring keys to limit exposure
* **Revoke unused keys** -- regularly audit and revoke keys that are no longer needed
* **Rotate keys** -- periodically create new keys and phase out old ones

## Permissions

Deploy key management requires the `org:update` permission. Only **Owners** and **Admins** can create, view, or revoke deploy keys. See [RBAC](/hub/rbac) for the full permissions matrix.