> This page location: /docs.md > /docs/management.md > /docs/atlas/operator/v2.15.md > /docs/atlas/operator/v2.15/configure-ak8so-access-to-atlas.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Configure Access to Atlas Using Service Accounts

## Overview

Atlas API Service Accounts provide a secure, token-based alternative to [Programmatic API Keys](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-about-org-api-keys) for authenticating Atlas Kubernetes Operator with the Atlas Administration API. Service Accounts use short-lived access tokens derived from a `clientId` and `clientSecret` pair, reducing the risk of long-lived credential exposure.

MongoDB recommends Service Accounts over Programmatic API Keys for new deployments. Service Accounts offer the following benefits:

- Token-based authentication with automatic token refresh managed by the operator.

- Support for both organization-level and project-level scopes.

- Auditable, distinct identity for your Atlas Kubernetes Operator workloads.

**Important: Service Account Secret Expiration**

Unlike API Keys, Service Account secrets are **expirable**. You can set a TTL (Time to Live) of up to one year maximum. You must rotate Service Account secrets before they expire to maintain uninterrupted access. Atlas automatically raises a **Service Account Secrets are about to
expire** alert as the expiry date approaches. Plan your rotation schedule accordingly.

This applies to both organization-level and project-level Service Accounts.

## Prerequisites

Before you begin, ensure you have the following:

- An Atlas account with the **Organization Owner** role for organization-level Service Accounts, or **Project Owner** role for project-level Service Accounts.

- A running Kubernetes cluster with Atlas Kubernetes Operator installed.

- `kubectl` access to the Kubernetes cluster where Atlas Kubernetes Operator runs.

## Procedure

1. Create the Service Account in Atlas

   Create a Service Account in Atlas using the Atlas UI or the Atlas Administration API. To learn how to create an organization-level Service Account, see [Create a Service Account in an Organization](https://www.mongodb.com/docs/atlas/configure-api-access/?interface=atlas-ui\&programmatic-access=service-account#create-a-service-account-for-an-organization). To learn how to create a project-level Service Account, see [Create a Service Account in a Project.](https://www.mongodb.com/docs/atlas/configure-api-access/?interface=atlas-ui\&programmatic-access=service-account#create-a-service-account-in-a-project)

   Copy the `clientId` and `clientSecret`. Store them securely because you cannot retrieve the `clientSecret` again after creation.

2. Create the Kubernetes Connection Secret

   Create a Kubernetes [secret](https://kubernetes.io/docs/concepts/configuration/secret/) containing the `orgId`, `clientId`, and `clientSecret`.

   - For a `global` Atlas Kubernetes Operator [secret](https://kubernetes.io/docs/concepts/configuration/secret/), run the following commands:

     **Note:**

     The name of the `global` Atlas Kubernetes Operator secret must conform to the predefined format. The default name of the Atlas Kubernetes Operator deployment is `mongodb-atlas-operator`. So, the [secret](https://kubernetes.io/docs/concepts/configuration/secret/) should be named `mongodb-atlas-operator-service-account`.

     ```sh
     kubectl create secret generic mongodb-atlas-operator-service-account \
        --from-literal="orgId=<the_atlas_organization_id>" \
        --from-literal="clientId=<the_service_account_client_id>" \
        --from-literal="clientSecret=<the_service_account_client_secret>" \
        -n <operator_namespace>

     kubectl label secret mongodb-atlas-operator-service-account \
        atlas.mongodb.com/type=credentials \
        -n mongodb-atlas-system
     ```

   - For a `project` Atlas Kubernetes Operator [secret](https://kubernetes.io/docs/concepts/configuration/secret/), run the following commands:

     ```sh
     kubectl create secret generic my-project-connection \
        --from-literal="orgId=<the_atlas_organization_id>" \
        --from-literal="clientId=<the_service_account_client_id>" \
        --from-literal="clientSecret=<the_service_account_client_secret>" \
        -n <atlas_project_namespace>

     kubectl label secret my-project-connection \
        atlas.mongodb.com/type=credentials \
        -n <atlas_project_namespace>
     ```

3. Reference the Secret from `AtlasProject`

   Reference the [secret](https://kubernetes.io/docs/concepts/configuration/secret/) from your `AtlasProject` custom resource using [spec.connectionSecretRef.name.](https://www.mongodb.com/docs/atlas/operator/v2.15/atlasproject-custom-resource.md#std-label-atlasproject-spec-connectionsecretref)

   If you created a `global` [secret](https://kubernetes.io/docs/concepts/configuration/secret/), all projects use it by default and no additional configuration is needed.

   If you created a `project` [secret](https://kubernetes.io/docs/concepts/configuration/secret/), add the `connectionSecretRef` to your `AtlasProject` custom resource:

   ```yaml
   apiVersion: atlas.mongodb.com/v1
   kind: AtlasProject
   metadata:
     name: my-project
   spec:
     name: "My Project"
     connectionSecretRef:
       name: my-project-connection
   ```

4. Verify the Operator Uses the Service Account

   After you configure the [secret](https://kubernetes.io/docs/concepts/configuration/secret/), verify that Atlas Kubernetes Operator authenticates successfully:

   ```sh
   kubectl get atlasproject my-project -o jsonpath='{.status.conditions}'
   ```

   Check that the `Ready` condition is `True`. If Atlas Kubernetes Operator can't authenticate with the Service Account credentials, the conditions show an error describing the issue.

## YAML Example

The following example shows a Connection Secret configured for a Service Account:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-project-connection
  namespace: atlas-operator
  labels:
    atlas.mongodb.com/type: credentials
type: Opaque
stringData:
  orgId: "5d39f0719ccf646554345678"
  clientId: "mdb_sa_id_67890abcdef1234567890abc"
  clientSecret: "mdb_sa_sk_abcdef1234567890abcdef12"
```

## Considerations

### Token Management

Atlas Kubernetes Operator manages access tokens automatically. When the Atlas Kubernetes Operator detects a Service Account Connection Secret, it obtains an access token from the Atlas Administration API and stores it in a separate Kubernetes [secret](https://kubernetes.io/docs/concepts/configuration/secret/). Do **not** manually edit or delete the Access Token Secret. Atlas Kubernetes Operator refreshes tokens as needed.

### Credential Rotation

When you rotate the Service Account secret in Atlas:

1. Update the Kubernetes Connection Secret with the new `clientSecret`.

2. The Atlas Kubernetes Operator detects the change and acquires a new access token on the next reconcile cycle. No restart is required.

**Important:**

Service Account secrets have a maximum TTL (Time to Live) of one year. Monitor the **Service Account Secrets are about to
expire** alert in Atlas and rotate your secrets before they expire to avoid authentication failures. This applies to both organization-level and project-level Service Accounts.

### IP Access List

The Service Account's API (Application Programming Interface) access list must include the egress IP (Internet Protocol) address or CIDR (Classless Inter-Domain Routing) block used by the Atlas Kubernetes Operator pod, the same as for [Programmatic API Keys](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-about-org-api-keys). If the operator pod's egress IP is not on the Service Account access list, API (Application Programming Interface) requests fail.
