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

# Credentials

> Enable agents to access your services

Credentials store secret keys, tokens, and authentication data for your services. All credentials are encrypted at rest, and agents can only access them programmatically during task execution (they never see the actual values).

<Frame caption="Credentials list: each row is a named secret with a scope (tenant or organization). Values are never displayed after creation.">
  <img src="https://mintcdn.com/2501/kr0HtinaCJPsc_vr/images/credentials_list.png?fit=max&auto=format&n=kr0HtinaCJPsc_vr&q=85&s=26260926190df778af79e3070841ece3" alt="Credentials list" width="2880" height="1800" data-path="images/credentials_list.png" />
</Frame>

## Managing Credentials

Go to **Command Center** → **Credentials** and click **New Credentials** to create an entry.

<img src="https://mintcdn.com/2501/FQCxzyD4KSOUqSjH/images/create_credential.png?fit=max&auto=format&n=FQCxzyD4KSOUqSjH&q=85&s=7e342c2844f34ee9321766baba0e4e71" alt="Credentials" width="1408" height="904" data-path="images/create_credential.png" />

### Name

A descriptive identifier for the credential. Use naming conventions that show its purpose and target system.

Example: `prod_db_ssh_root` or `aws_prod_api_key`

### Description

Additional context about what this credential is for.

Example: `Root SSH credentials for production Ubuntu database server`

### Scope

By default, credentials are scoped to the current organization, so only that org's agents can use them. Switch the scope to **Tenant** to make a credential available to all organizations.

### Type

* **Value**: Store the credential directly in 2501's encrypted storage
* **Vault Path**: Reference a secret stored in an external vault like HashiCorp Vault

When using vault paths, make sure the vault is accessible from where your agents run.

### Value

The actual credential data or vault path reference. All values are encrypted and only decrypted when needed.

⚠️ **Important:** Escape special characters properly to prevent authentication errors.

### Agent Accessible

Controls whether agents can use this credential during tasks.

**Enable for:**

* SSH configurations for remote execution
* API keys for CLI tools
* Database credentials for queries
* Any credential the agent needs to pass to commands

**Disable for:**

* Service credentials used only by 2501 infrastructure
* MCP server authentication tokens
* Backend service bearer tokens

## Assigning Credentials to Agents

When creating or editing an [agent](/0.7/core-concepts/agents), find the credentials section to assign what's needed.

<img src="https://mintcdn.com/2501/gMl_w8qww9Zl47hO/images/remote_execution.png?fit=max&auto=format&n=gMl_w8qww9Zl47hO&q=85&s=2a05c05565afd7785b45d7ddb5240830" alt="Assign Creds" width="1358" height="180" data-path="images/remote_execution.png" />

For each credential, configure:

* **Role**: How the credential will be used (see below)
* **Priority**: Order of precedence when multiple credentials of the same role exist
* **Required**: Whether the agent can work without it

Only credentials marked "Agent Accessible" will show up here.

## Credential Roles

Roles define how agents use credentials during execution. They cover remote access over SSH:

* **SSH Username**: Remote system login name
* **SSH Password**: Password-based SSH authentication
* **SSH Private Key**: Private key for key-based authentication
* **SSH Public Key**: Public key (rarely needed)

## Common Use Cases

**SSH Remote Execution (key-based)**\
Roles: SSH Username, SSH Private Key\
Agent Accessible: Yes\
Required: Yes

**SSH Remote Execution (password-based)**\
Roles: SSH Username, SSH Password\
Agent Accessible: Yes\
Required: Yes

## Credential Priority

When multiple credentials with the same role are assigned to an agent, priority determines which gets tried first. Lower numbers = higher priority.

Useful for:

* Failover scenarios (try primary, fall back to secondary)
* Multi-environment access (different credentials for different systems)
* Credential rotation (keep old credentials briefly while transitioning)

## Windows Authentication with gMSA

Windows (WinRM) hosts can authenticate using a gMSA (group Managed Service Account) over Kerberos instead of a static Windows username and password. This avoids storing a long-lived Windows admin password.

Manage these under **Command Center** → **Credentials** → **gMSA Configurations**. Administrators can create, edit, and delete configurations.

Before adding a gMSA configuration, create a credential holding the password of the Active Directory service account that 2501 binds as. The configuration references that credential and captures the AD connection details:

* The **gMSA account** (its `sAMAccountName`, ending in `$`) and the AD **realm**
* The **Domain Controller** host and **LDAPS port** (default `636`)
* The **LDAP search base** and the **bind DN** of the service account
* Optional **KDC endpoints**, and for domain controllers that use a private certificate authority, a **PEM CA certificate** for the LDAPS connection

One configuration can serve multiple Windows hosts that share the same gMSA, and a configuration that is still attached to hosts cannot be deleted. When a host uses gMSA authentication, 2501 reads the managed password from Active Directory over LDAPS and obtains a Kerberos ticket to authenticate to WinRM, bypassing the static password path.

## Security Best Practices

Only mark credentials as "Agent Accessible" when necessary. Use organization-level scoping to limit exposure. Rotate credentials regularly and after any suspected compromise. For production systems, prefer vault paths over direct values. Review which agents have access to sensitive credentials, and always document the credential's purpose clearly.