Atlas Administration API Authentication
- OAuth 2.0 authentication for programmatic access to Atlas is available as a Preview feature.
- The feature and the corresponding documentation might change at any time during the Preview period. To use OAuth 2.0 authentication, create a service account to use in your requests to the Atlas Administration API.
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.