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

# Credentials and tokens

> How to configure credentials, Connected Apps, connectors, and secret rotation in Acrity.

Configuring credentials and tokens requires a Workspace admin (platform admins also have access). You set them up through the Console so Acrity can read changes, publish review results, and integrate work management providers.

## Where to configure

| Need                 | Console location | When to use                                                                                                                                |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| OAuth or GitHub App  | `Connected Apps` | recommended flow for GitHub, GitLab, Bitbucket, Azure DevOps, Jira, Linear, and ClickUp when the provider supports delegated authorization |
| Manual credential    | `Credentials`    | tokens or credentials created outside the OAuth flow                                                                                       |
| Private/on-prem VCS  | `Connectors`     | when the VCS is on a private network or when the VCS token must remain in the customer's environment                                       |
| Programmatic API use | `API Keys`       | internal integrations, automations, and MCP                                                                                                |
| Outbound webhooks    | `Webhooks`       | sending Acrity events to external systems                                                                                                  |

## How secrets are stored

Credential secrets, OAuth tokens, and sensitive overrides are stored encrypted in the database with AES-256-GCM. API key data uses a different model: the complete key is shown once and Acrity stores only an HMAC-SHA-256 hash with pepper for verification.

Connector tokens follow the one-time display principle. The complete token appears at creation or rotation time; after that, Acrity keeps a SHA-256 hash for verification, not reusable plaintext.

<Warning>
  Copy one-time displayed secrets to your company's secrets vault. Acrity does not show the complete value again.
</Warning>

## Connected Apps

Use `Connected Apps` when you want a guided authorization flow. This flow reduces manual error, enables reauthorization in the Console, and shows when the installation needs new permission.

Recommended flow:

<Steps>
  <Step title="Open the workspace">
    Select the correct workspace in the Console.
  </Step>

  <Step title="Go to Connected Apps">
    Choose the provider and start installation or authorization.
  </Step>

  <Step title="Grant permissions in the provider">
    Confirm the authorized organization, account, repositories, or projects.
  </Step>

  <Step title="Link to repositories">
    Return to the Console and connect repositories or link the PM integration in the repository detail page.
  </Step>
</Steps>

## Manual credentials

Use `Credentials` when the provider requires a manual token, when the organization already has dedicated credentials, or when an OAuth flow is not appropriate.

When creating a credential:

1. Choose the provider.
2. Define a name that helps audit, such as `github-app-prod` or `jira-service-account`.
3. Fill in the fields required by the provider.
4. Validate the credential before linking it to repositories.
5. Use the credential only in repositories that need it.

## Connectors

Use `Connectors` when the VCS is on a private network or when internal policy requires the VCS token to remain in the customer's environment. The connector is installed in the customer's infrastructure and maintains the required bridge with Acrity.

In the Console, a Workspace admin creates the connector, chooses the provider, downloads the installation artifact, and copies the one-time displayed secrets. The connector page shows status, heartbeat, discovered repositories, and rotation actions.

## Rotation

Rotate secrets when:

* a person with access to the secret leaves the team;
* a token was copied to an unsafe location;
* the provider requires renewal;
* an integration stops being used;
* internal policy defines a periodic cycle.

After rotating, validate the credential or connector and track the status of linked repositories.