> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Atlas Administration API Authentication Methods **Important:** We recommend you use service accounts instead of API (Application Programming Interface) keys to authenticate to the Atlas Administration API. API (Application Programming Interface) keys are a legacy authentication method. To use the Atlas Administration API to manage your Atlas clusters, you must authenticate your API (Application Programming Interface) requests. The Atlas Administration API accepts the following authentication methods: - Service account access tokens ([OAuth 2.0)](https://oauth.net/2/) - API keys ([HTTP Digest Authentication)](http://en.wikipedia.org/wiki/Digest_access_authentication) To learn how to use service accounts and API (Application Programming Interface) keys to configure programmatic access to your Atlas organizations and projects, see the [Atlas Administration API Getting Started](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-atlas-admin-api-access) guide. The Atlas Administration API doesn't provide access to the data stored in your clusters. To read or write data in a database, you must authenticate to your cluster using the credentials for a [database user](https://www.mongodb.com/docs/manual/reference/database-users.md#std-label-security-database-users) with the appropriate read or write [roles](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-database-user-roles). You can use the Atlas Administration API to create and manage database users. **Note:** Many Atlas Administration API endpoint URLs (Uniform Resource Locators) follow the format of `/api/atlas//groups//`, where `` is your [project ID](https://www.mongodb.com/docs/atlas/api/atlas-admin-api-ref.md#std-label-project-id). For these resources, the service account or API (Application Programming Interface) keys that you use to authenticate the request must be a member of the organization that hosts the project. Otherwise, Atlas responds with a [401](https://httpstatuses.com/401) error. The following sections describe the Atlas Administration API authentication methods: ## Service Accounts Overview Service accounts are the recommended method to manage authentication to the Atlas Administration API. Service accounts provide improved security over API (Application Programming Interface) keys by using the industry standard [OAuth 2.0](https://oauth.net/2/) protocol with the [Client Credentials flow.](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) A service account lets you manage permissions and create access tokens that authenticate API (Application Programming Interface) requests. Each service account has a client ID and a [rotatable secret](https://www.mongodb.com/docs/atlas/tutorial/rotate-service-account-secrets.md#std-label-rotate-service-account-secrets) that function as a username and a password for creating access tokens. To learn how to construct an API (Application Programming Interface) request with an access token, see [Make an API (Application Programming Interface) Request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request) **Tip: Service Account Token Best Practices** Consider the following best practices when using service account tokens: - **Reuse tokens**: Service account access tokens have a 1 hour (3600 seconds) lifespan, during which you can reuse the token multiple times. Avoid creating new tokens for every request. - **Generate new tokens when needed**: While you can't refresh an access token, you can [generate a new token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) when your current token is close to expiry. This prevents service interruptions and allows you to maintain authorized service account access. - **Revoke unnecessary tokens**: When you no longer need a token, [revoke the token's access](https://www.mongodb.com/docs/atlas/api/service-accounts/revoke-oauth2-token.md#std-label-revoke-oauth2-token-atlas) to minimize security risks and ensure that only active tokens have access to your service account. Each service account belongs to exactly one organization, and you can grant it access to any number of projects within that organization. To give an organization-level service account access to a project, see [Grant Existing Service Account Access to a Project.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-invite-org-app-api-keys) Atlas [roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-user-roles) limit which operations a service account can authenticate with its access token. You must assign roles to service accounts as you would for users to ensure that the service account generates access tokens with the necessary permissions for the desired API (Application Programming Interface) calls. **Important:** If a project-level service account has access to the organization or to other projects, you must have the [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) role to manage its lifecycle, including rotating or revoking its secrets. You can't use a service account or its access token to log into Atlas through the Atlas UI. Service accounts only grant access to the Atlas Administration API, which does not include UI access or access to cluster data. To learn more about the limitations of service accounts, see [MongoDB Limits and Thresholds.](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-server-limits-thresholds) ## API Keys Overview **Important:** We recommend you use service accounts instead of API (Application Programming Interface) keys to authenticate to the Atlas Administration API. API (Application Programming Interface) keys are a legacy authentication method. API keys are a legacy method of authenticating to the Atlas Administration API that uses [HTTP Digest Authentication.](http://en.wikipedia.org/wiki/Digest_access_authentication) API (Application Programming Interface) keys have two parts: a Public Key and a Private Key. These serve the same function as a username and a password to authenticate API (Application Programming Interface) requests. To learn how to construct an API (Application Programming Interface) request using API (Application Programming Interface) keys, see [Make an API (Application Programming Interface) Request.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-example-api-request) Atlas hashes the Public Key and Private Key using a unique value called a **nonce**. The nonce is only valid for a short amount of time as per the [HTTP Digest Authentication](http://en.wikipedia.org/wiki/Digest_access_authentication) specification. This limited lifespan protects against replay attacks, where an attacker caches a Private Key to use it without time restriction. Each pair of API (Application Programming Interface) keys belongs to only one organization, and can grant access to any number of projects in that organization. To give organization-level API (Application Programming Interface) keys access to a project, see [Grant Existing Service Account Access to a Project.](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-invite-org-app-api-keys) Atlas [roles](https://www.mongodb.com/docs/atlas/reference/user-roles.md#std-label-user-roles) limit which operations API (Application Programming Interface) keys can perform. You must assign roles to API (Application Programming Interface) keys as you would for users to ensure the API (Application Programming Interface) keys have the necessary permissions for the desired API (Application Programming Interface) calls. You can't use API (Application Programming Interface) keys to log into Atlas through the Atlas UI. API (Application Programming Interface) keys only grant access to the Atlas Administration API, which does not include UI access or access to cluster data. ## Next Steps To learn how to use and manage service accounts and API (Application Programming Interface) keys, see the following procedures: - [Grant Programmatic Access to an Organization](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-create-org-api-key) - [Grant Programmatic Access to a Project](https://www.mongodb.com/docs/atlas/configure-api-access.md#std-label-about-project-api-keys) - [Manage Programmatic Access to an Organization](https://www.mongodb.com/docs/atlas/configure-api-access-org.md#std-label-atlas-admin-api-access-org) - [Manage Programmatic Access to a Project](https://www.mongodb.com/docs/atlas/configure-api-access-project.md#std-label-atlas-admin-api-access-project) - [Manage Programmatic Access to Multiple Organizations](https://www.mongodb.com/docs/atlas/configure-api-access-mult-org.md#std-label-prog-access-mult-orgs) - [Generate Service Account Token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token.md#std-label-generate-oauth2-token-atlas) - [Revoke Service Account Token](https://www.mongodb.com/docs/atlas/api/service-accounts/revoke-oauth2-token.md#std-label-revoke-oauth2-token-atlas)