Docs Menu
Docs Home
/
MongoDB Atlas
/ /

Atlas Administration API Authentication

You can use one of two methods to authenticate to the Atlas Administration API:

API Keys
Service Account (Preview)
Legacy method of authenticating to Atlas that uses HTTP Digest Authentication.
New method of authenticating to Atlas using the industry standard OAuth 2.0 protocol with the Client Credentials flow. Currently in Preview.
API keys have two parts: a Public Key and a Private Key. These two parts serve the same function as a username and a password when you make API requests to Atlas.
A service account lets you manage permissions and create access tokens. A service account has a client ID and a secret that function as a username and a password for creating access tokens. An access token lets you make API requests to Atlas.
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 specification. This is to prevent replay attacks, so you can't cache a nonce and use it forever.
After you create a service account, you'll use its client ID and secret to generate an access token, which authenticates your API requests. Access tokens are only valid for 1 hour (3600 seconds) per the OAuth 2.0 specification. Expiration of access tokens prevents replay attacks, where a leaked access token could be used without a time restriction.
Atlas roles limit which operations API keys can perform. You must grant roles to API keys as you would for users to ensure the API keys can call API endpoints without errors.
Atlas roles limit which operations a service account can perform with its access token. You must grant roles to service accounts as you would for users to ensure the access token can call API endpoints without errors.
Atlas binds many resources to a project. Many API resource URLs follow the format of /api/atlas/<version>/groups/<GROUP-ID>/, where <GROUP-ID> is your project ID. For these resources, the API keys must be a member of the organization that hosts the project. Otherwise, Atlas responds with a 401 error. To give the organization-level API keys access to a project, see Assign Existing Organization Access to a Project.
Atlas binds many resources to a project. Many API resource URLs follow the format of /api/atlas/<version>/groups/<GROUP-ID>/, where <GROUP-ID> is your project ID. For these resources, the service account must be a member of the organization that hosts the project. Otherwise, Atlas responds with a 401 error. To give the organization-level service account access to a project, see Assign Existing Organization Access to a Project.
Each API key belongs to only one organization, but you can grant API keys access to any number of projects in that organization.
Each service account belongs to only one organization, but you can grant a service account access to any number of projects in that organization.
You can't use API keys to log into Atlas through the Atlas UI.
You can't use a service account or its access token to log into Atlas through the Atlas UI.

To configure your preferred method of authenticating to the Atlas Administration API, see Grant Programmatic Access to an Organization.

Tip

See also:

Back

Admin API Overview