CircleCI Authentication: Methods, Setup, and Security (2026)

Authentication overview

CircleCI provides several authentication mechanisms to secure access to its platform and API, ensuring that only authorized users and systems can interact with your CI/CD pipelines and data. These methods range from user-specific credentials for individual access to programmatic tokens for automated workflows and integrations. The choice of authentication method typically depends on the specific use case, such as accessing the CircleCI web interface, programmatically interacting with the CircleCI API, or securely cloning private repositories during a build.

Effective authentication is foundational to maintaining the security and integrity of your continuous integration and continuous delivery (CI/CD) processes. CircleCI's approach to authentication is designed to integrate with common development workflows, supporting version control systems (VCS) like GitHub and Bitbucket, while also providing granular control over API access. Understanding the distinctions between these methods and their appropriate applications is crucial for secure pipeline management.

Supported authentication methods

CircleCI supports a range of authentication methods tailored for different interaction types:

• OAuth for VCS Integration: When you initially sign up for CircleCI or link a new project, you authenticate through your Version Control System (VCS) provider, such as GitHub or Bitbucket. This process uses OAuth 2.0, a standard protocol for delegated authorization, allowing CircleCI to access your repositories without directly handling your VCS credentials. OAuth enables CircleCI to list your repositories, set up webhooks, and perform actions on your behalf within the scope of permissions you grant. For details on how OAuth works, refer to the OAuth 2.0 specification.
• API Tokens: For programmatic access to the CircleCI API, API tokens are the primary method. These tokens are essentially long-lived passwords that grant specific permissions. CircleCI offers different types of API tokens:
• Personal API Tokens: These are associated with your user account and grant access equivalent to your permissions within the CircleCI application. They are suitable for personal scripts, CLI usage, and integrations where user-level access is appropriate.
• Project API Tokens: These tokens are scoped to a specific project and can be used for automated processes that only need to interact with that project. This provides a more granular approach to security, limiting the blast radius if a token is compromised.
• User API Tokens: Similar to personal tokens, but can be managed by an organization administrator for users.
• SSH Keys: SSH keys are used primarily for securely cloning private repositories within a CircleCI build environment and for executing remote commands on external servers. CircleCI allows you to add SSH keys to your projects, which are then injected into the build containers. This method relies on public-key cryptography, where a public key is stored on the remote server (e.g., your VCS provider or a deployment target) and the corresponding private key is securely managed by CircleCI for your builds. For more information on SSH, consult the IETF's SSH Protocol Architecture document.

Here's a comparison of the primary authentication methods:

Getting your credentials

The process for obtaining and configuring credentials varies by method:

API Tokens

1. Personal API Tokens: Navigate to your CircleCI User Settings, then to the 'Personal API Tokens' section. Click 'Create New Token', provide a name, and copy the generated token. This token will only be shown once, so store it securely.
2. Project API Tokens: For project-specific tokens, go to your project's settings in the CircleCI web application, then to 'API Permissions'. You can generate a token that is explicitly tied to that project. Refer to the CircleCI documentation on project API tokens for detailed steps.

Once you have an API token, you typically pass it in the Circle-Token header or as a query parameter for API requests.

SSH Keys

To use SSH keys with CircleCI:

1. Generate an SSH key pair: If you don't have one, generate a new SSH key pair on your local machine. Instructions are widely available for various operating systems; for example, the GitHub documentation on generating SSH keys provides a comprehensive guide.
2. Add the public key to your VCS or server: Add the public part of your SSH key to your VCS provider (e.g., GitHub deploy keys) or to the ~/.ssh/authorized_keys file on your remote server.
3. Add the private key to CircleCI: In your CircleCI project settings, navigate to 'SSH Keys'. You can add your private SSH key here. CircleCI will then make this key available to your build containers for secure operations. The CircleCI guide for adding SSH keys provides specific instructions.

Authenticated request example

Here's an example of an authenticated request to the CircleCI API v2 using a personal API token to list your user's pipelines. Replace <YOUR_PERSONAL_API_TOKEN> with your actual token.

curl --request GET \
  --url https://circleci.com/api/v2/pipeline \
  --header 'Circle-Token: <YOUR_PERSONAL_API_TOKEN>'

This command uses curl to make a GET request to the /pipeline endpoint of the CircleCI API v2. The Circle-Token header carries the personal API token, authenticating the request and granting access based on the token's permissions.

Security best practices

Adhering to security best practices for authentication is critical for protecting your CI/CD pipelines and the code within them:

• Use Least Privilege: Grant only the minimum necessary permissions to API tokens and SSH keys. For instance, use Project API Tokens for automated tasks that only need access to a single project, rather than a Personal API Token with broader access.
• Rotate Credentials Regularly: Periodically rotate your API tokens and SSH keys. This practice minimizes the window of opportunity for a compromised credential to be exploited. CircleCI's documentation on revoking API tokens can guide this process.
• Store Credentials Securely: Never hardcode API tokens or private SSH keys directly into your configuration files or source code. Instead, use CircleCI's built-in mechanisms for secure credential storage:
• Environment Variables: For sensitive values needed during a build, define them as environment variables in your project settings. These are encrypted and not exposed in build logs.
• Contexts: For sharing environment variables across multiple projects or workflows, use Contexts. Contexts allow you to define a set of environment variables once and apply them to various projects or jobs, enhancing security and reusability.
• Monitor Access: Regularly review audit logs and access patterns for suspicious activity related to your CircleCI account and projects.
• Enable Two-Factor Authentication (2FA): For your CircleCI user account and your linked VCS account (GitHub, Bitbucket), enable 2FA. This adds an extra layer of security, requiring a second verification method beyond just a password.
• Limit SSH Key Exposure: Ensure that SSH keys used for deployment or accessing external resources are restricted to specific IP addresses where possible, and only grant necessary permissions on the target system.
• Use Deploy Keys for Repositories: When cloning private repositories, use deploy keys rather than personal SSH keys where appropriate. Deploy keys are repository-specific and can be read-only, limiting their potential impact if compromised.
• Understand OAuth Scopes: When granting OAuth permissions to CircleCI through your VCS, understand the scopes being requested. Only grant the minimum necessary permissions for CircleCI to function.

By implementing these practices, you can significantly enhance the security posture of your CircleCI environment and protect your build processes from unauthorized access and potential vulnerabilities.