Create One Identity Provider

POST /api/atlas/v2/federationSettings/{federationSettingsId}/identityProviders

Creates one identity provider within the specified federation. To use this resource, the requesting Service Account or API Key must have the Organization Owner role in one of the connected organizations.

Note: This resource only supports the creation of OIDC identity providers.

Path parameters

federationSettingsId string Required

Unique 24-hexadecimal digit string that identifies your federation.

Format should match the following pattern: ^([a-f0-9]{24})$.

Query parameters

envelope boolean

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Default value is false.

application/vnd.atlas.2023-11-15+json

Body object Required

The identity provider that you want to create.

audience string

Identifier of the intended recipient of the token.
authorizationType string

Indicates whether authorization is granted based on group membership or user ID.

Values are GROUP or USER.
description string

The description of the identity provider.
displayName string

Human-readable label that identifies the identity provider.

Minimum length is 1, maximum length is 50.
groupsClaim string

Identifier of the claim which contains IdP Group IDs in the token.
idpType string

String enum that indicates the type of the identity provider. Default is WORKFORCE.

Values are WORKFORCE or WORKLOAD.
issuerUri string

Unique string that identifies the issuer of the SAML Assertion or OIDC metadata/discovery document URL.
protocol string

String enum that indicates the protocol of the identity provider. Either SAML or OIDC.

Values are SAML or OIDC.
userClaim string

Identifier of the claim which contains the user ID in the token.
associatedDomains array[string]

List that contains the domains associated with the identity provider.
clientId string

Client identifier that is assigned to an application by the Identity Provider.
requestedScopes array[string]

Scopes that MongoDB applications will request from the authorization endpoint.

audience string

Identifier of the intended recipient of the token.
authorizationType string

Indicates whether authorization is granted based on group membership or user ID.

Values are GROUP or USER.
description string

The description of the identity provider.
displayName string

Human-readable label that identifies the identity provider.

Minimum length is 1, maximum length is 50.
groupsClaim string

Identifier of the claim which contains IdP Group IDs in the token.
idpType string

String enum that indicates the type of the identity provider. Default is WORKFORCE.

Values are WORKFORCE or WORKLOAD.
issuerUri string

Unique string that identifies the issuer of the SAML Assertion or OIDC metadata/discovery document URL.
protocol string

String enum that indicates the protocol of the identity provider. Either SAML or OIDC.

Values are SAML or OIDC.
userClaim string

Identifier of the claim which contains the user ID in the token.

Responses

200 application/vnd.atlas.2023-11-15+json

OK
One of:
FederationOidcWorkforceIdentityProvider object FederationOidcWorkloadIdentityProvider object
Hide attributes Show attributes

associatedOrgs array[object]

List that contains the connected organization configurations associated with the identity provider.

Hide associatedOrgs attributes Show associatedOrgs attributes object

dataAccessIdentityProviderIds array[string]

The collection of unique ids representing the identity providers that can be used for data access in this organization.

domainAllowList array[string]

Approved domains that restrict users who can join the organization based on their email address.

domainRestrictionEnabled boolean Required

Value that indicates whether domain restriction is enabled for this connected org.

identityProviderId string

Legacy 20-hexadecimal digit string that identifies the UI access identity provider that this connected org config is associated with. This id can be found within the Federation Management Console > Identity Providers tab by clicking the info icon in the IdP ID row of a configured identity provider.

Format should match the following pattern: ^([a-f0-9]{20})$.

orgId string Required

Unique 24-hexadecimal digit string that identifies the connected organization configuration.

Format should match the following pattern: ^([a-f0-9]{24})$.

postAuthRoleGrants array[string]

Atlas roles that are granted to a user in this organization after authenticating. Roles are a human-readable label that identifies the collection of privileges that MongoDB Cloud grants a specific MongoDB Cloud user. These roles can only be organization specific roles.

Values are ORG_OWNER, ORG_MEMBER, ORG_GROUP_CREATOR, ORG_BILLING_ADMIN, ORG_BILLING_READ_ONLY, or ORG_READ_ONLY.

roleMappings array[object]

Role mappings that are configured in this organization.

Mapping settings that link one IdP and MongoDB Cloud.

Hide roleMappings attributes Show roleMappings attributes object

externalGroupName string Required

Unique human-readable label that identifies the identity provider group to which this role mapping applies.

Minimum length is 1, maximum length is 200.

id string

Unique 24-hexadecimal digit string that identifies this role mapping.

Format should match the following pattern: ^([a-f0-9]{24})$.

roleAssignments array[object]

Atlas roles and the unique identifiers of the groups and organizations associated with each role. The array must include at least one element with an Organization role and its respective orgId. Each element in the array can have a value for orgId or groupId, but not both.

Hide roleAssignments attributes Show roleAssignments attributes object

groupId string

Unique 24-hexadecimal digit string that identifies the project to which this role belongs. Each element within roleAssignments can have a value for groupId or orgId, but not both.

Format should match the following pattern: ^([a-f0-9]{24})$.

orgId string

Unique 24-hexadecimal digit string that identifies the organization to which this role belongs. Each element within roleAssignments can have a value for orgId or groupId, but not both.

Format should match the following pattern: ^([a-f0-9]{24})$.

role string

Human-readable label that identifies the collection of privileges that MongoDB Cloud grants a specific API key, MongoDB Cloud user, or MongoDB Cloud team. These roles include organization- and project-level roles.

Values are ORG_OWNER, ORG_MEMBER, ORG_GROUP_CREATOR, ORG_BILLING_ADMIN, ORG_BILLING_READ_ONLY, ORG_READ_ONLY, GROUP_BACKUP_MANAGER, GROUP_CLUSTER_MANAGER, GROUP_DATA_ACCESS_ADMIN, GROUP_DATA_ACCESS_READ_ONLY, GROUP_DATA_ACCESS_READ_WRITE, GROUP_DATABASE_ACCESS_ADMIN, GROUP_OBSERVABILITY_VIEWER, GROUP_OWNER, GROUP_READ_ONLY, GROUP_SEARCH_INDEX_EDITOR, or GROUP_STREAM_PROCESSING_OWNER.

userConflicts array[object]

List that contains the users who have an email address that doesn't match any domain on the allowed list.

MongoDB Cloud user linked to this federated authentication.

Hide userConflicts attributes Show userConflicts attributes object

emailAddress string(email) Required

Email address of the MongoDB Cloud user linked to the federated organization.

federationSettingsId string Required

Unique 24-hexadecimal digit string that identifies the federation to which this MongoDB Cloud user belongs.

Format should match the following pattern: ^([a-f0-9]{24})$.

firstName string Required

First or given name that belongs to the MongoDB Cloud user.

lastName string Required

Last name, family name, or surname that belongs to the MongoDB Cloud user.

userId string

Unique 24-hexadecimal digit string that identifies this user.

Format should match the following pattern: ^([a-f0-9]{24})$.

audience string

Identifier of the intended recipient of the token.

authorizationType string

Indicates whether authorization is granted based on group membership or user ID.

Values are GROUP or USER.

createdAt string(date-time)

Date that the identity provider was created on. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

description string

The description of the identity provider.

displayName string

Human-readable label that identifies the identity provider.

groupsClaim string

Identifier of the claim which contains IdP Group IDs in the token.

id string Required

Unique 24-hexadecimal digit string that identifies the identity provider.

Format should match the following pattern: ^([a-f0-9]{24})$.

idpType string

String enum that indicates the type of the identity provider. Default is WORKFORCE.

Values are WORKFORCE or WORKLOAD.

issuerUri string

Unique string that identifies the issuer of the SAML Assertion or OIDC metadata/discovery document URL.

oktaIdpId string Required

Legacy 20-hexadecimal digit string that identifies the identity provider.

Format should match the following pattern: ^([a-f0-9]{20})$.

protocol string

String enum that indicates the protocol of the identity provider. Either SAML or OIDC.

Values are SAML or OIDC.

updatedAt string(date-time)

Date that the identity provider was last updated on. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

userClaim string

Identifier of the claim which contains the user ID in the token.

associatedDomains array[string]

List that contains the domains associated with the identity provider.

clientId string

Client identifier that is assigned to an application by the Identity Provider.

requestedScopes array[string]

Scopes that MongoDB applications will request from the authorization endpoint.
Hide attributes Show attributes

associatedOrgs array[object]

List that contains the connected organization configurations associated with the identity provider.

Hide associatedOrgs attributes Show associatedOrgs attributes object

dataAccessIdentityProviderIds array[string]

The collection of unique ids representing the identity providers that can be used for data access in this organization.

domainAllowList array[string]

Approved domains that restrict users who can join the organization based on their email address.

domainRestrictionEnabled boolean Required

Value that indicates whether domain restriction is enabled for this connected org.

identityProviderId string

Legacy 20-hexadecimal digit string that identifies the UI access identity provider that this connected org config is associated with. This id can be found within the Federation Management Console > Identity Providers tab by clicking the info icon in the IdP ID row of a configured identity provider.

Format should match the following pattern: ^([a-f0-9]{20})$.

orgId string Required

Unique 24-hexadecimal digit string that identifies the connected organization configuration.

Format should match the following pattern: ^([a-f0-9]{24})$.

postAuthRoleGrants array[string]

Atlas roles that are granted to a user in this organization after authenticating. Roles are a human-readable label that identifies the collection of privileges that MongoDB Cloud grants a specific MongoDB Cloud user. These roles can only be organization specific roles.

Values are ORG_OWNER, ORG_MEMBER, ORG_GROUP_CREATOR, ORG_BILLING_ADMIN, ORG_BILLING_READ_ONLY, or ORG_READ_ONLY.

roleMappings array[object]

Role mappings that are configured in this organization.

Mapping settings that link one IdP and MongoDB Cloud.

Hide roleMappings attributes Show roleMappings attributes object

externalGroupName string Required

Unique human-readable label that identifies the identity provider group to which this role mapping applies.

Minimum length is 1, maximum length is 200.

id string

Unique 24-hexadecimal digit string that identifies this role mapping.

Format should match the following pattern: ^([a-f0-9]{24})$.

roleAssignments array[object]

Atlas roles and the unique identifiers of the groups and organizations associated with each role. The array must include at least one element with an Organization role and its respective orgId. Each element in the array can have a value for orgId or groupId, but not both.

Hide roleAssignments attributes Show roleAssignments attributes object

groupId string

Unique 24-hexadecimal digit string that identifies the project to which this role belongs. Each element within roleAssignments can have a value for groupId or orgId, but not both.

Format should match the following pattern: ^([a-f0-9]{24})$.

orgId string

Unique 24-hexadecimal digit string that identifies the organization to which this role belongs. Each element within roleAssignments can have a value for orgId or groupId, but not both.

Format should match the following pattern: ^([a-f0-9]{24})$.

role string

Human-readable label that identifies the collection of privileges that MongoDB Cloud grants a specific API key, MongoDB Cloud user, or MongoDB Cloud team. These roles include organization- and project-level roles.

Values are ORG_OWNER, ORG_MEMBER, ORG_GROUP_CREATOR, ORG_BILLING_ADMIN, ORG_BILLING_READ_ONLY, ORG_READ_ONLY, GROUP_BACKUP_MANAGER, GROUP_CLUSTER_MANAGER, GROUP_DATA_ACCESS_ADMIN, GROUP_DATA_ACCESS_READ_ONLY, GROUP_DATA_ACCESS_READ_WRITE, GROUP_DATABASE_ACCESS_ADMIN, GROUP_OBSERVABILITY_VIEWER, GROUP_OWNER, GROUP_READ_ONLY, GROUP_SEARCH_INDEX_EDITOR, or GROUP_STREAM_PROCESSING_OWNER.

userConflicts array[object]

List that contains the users who have an email address that doesn't match any domain on the allowed list.

MongoDB Cloud user linked to this federated authentication.

Hide userConflicts attributes Show userConflicts attributes object

emailAddress string(email) Required

Email address of the MongoDB Cloud user linked to the federated organization.

federationSettingsId string Required

Unique 24-hexadecimal digit string that identifies the federation to which this MongoDB Cloud user belongs.

Format should match the following pattern: ^([a-f0-9]{24})$.

firstName string Required

First or given name that belongs to the MongoDB Cloud user.

lastName string Required

Last name, family name, or surname that belongs to the MongoDB Cloud user.

userId string

Unique 24-hexadecimal digit string that identifies this user.

Format should match the following pattern: ^([a-f0-9]{24})$.

audience string

Identifier of the intended recipient of the token.

authorizationType string

Indicates whether authorization is granted based on group membership or user ID.

Values are GROUP or USER.

createdAt string(date-time)

Date that the identity provider was created on. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

description string

The description of the identity provider.

displayName string

Human-readable label that identifies the identity provider.

groupsClaim string

Identifier of the claim which contains IdP Group IDs in the token.

id string Required

Unique 24-hexadecimal digit string that identifies the identity provider.

Format should match the following pattern: ^([a-f0-9]{24})$.

idpType string

String enum that indicates the type of the identity provider. Default is WORKFORCE.

Values are WORKFORCE or WORKLOAD.

issuerUri string

Unique string that identifies the issuer of the SAML Assertion or OIDC metadata/discovery document URL.

oktaIdpId string Required

Legacy 20-hexadecimal digit string that identifies the identity provider.

Format should match the following pattern: ^([a-f0-9]{20})$.

protocol string

String enum that indicates the protocol of the identity provider. Either SAML or OIDC.

Values are SAML or OIDC.

updatedAt string(date-time)

Date that the identity provider was last updated on. This parameter expresses its value in the ISO 8601 timestamp format in UTC.

userClaim string

Identifier of the claim which contains the user ID in the token.
400 application/json

Bad Request.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
401 application/json

Unauthorized.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
403 application/json

Forbidden.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
404 application/json

Not Found.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
500 application/json

Internal Server Error.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.

POST /api/atlas/v2/federationSettings/{federationSettingsId}/identityProviders

atlas api createIdentityProvider --help

import (
	"os"
	"context"
	"log"
	sdk "go.mongodb.org/atlas-sdk/v20250312001/admin"
)

func main() {
	ctx := context.Background()
	clientID := os.Getenv("MONGODB_ATLAS_CLIENT_ID")
	clientSecret := os.Getenv("MONGODB_ATLAS_CLIENT_SECRET")

	client, err := sdk.NewClient(
		sdk.UseOAuthAuth(clientID, clientSecret),
		sdk.UseBaseURL(url))

	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	params = &sdk.CreateIdentityProviderApiParams{}
	sdkResp, httpResp, err := client.FederatedAuthenticationApi.
		CreateIdentityProviderWithParams(ctx, params).
		Execute()
}

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  --header "Content-Type: application/json" \
  -X POST "https://cloud.mongodb.com/api/atlas/v2/federationSettings/{federationSettingsId}/identityProviders" \
  -d '{ <Payload> }'

curl --user "${PUBLIC_KEY}:${PRIVATE_KEY}" \
  --digest \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  --header "Content-Type: application/json" \
  -X POST "https://cloud.mongodb.com/api/atlas/v2/federationSettings/{federationSettingsId}/identityProviders" \
  -d '{ <Payload> }'

Request examples

{
  "audience": "string",
  "authorizationType": "GROUP",
  "description": "string",
  "displayName": "string",
  "groupsClaim": "string",
  "idpType": "WORKFORCE",
  "issuerUri": "urn:idp:default",
  "protocol": "SAML",
  "userClaim": "string",
  "associatedDomains": [
    "string"
  ],
  "clientId": "string",
  "requestedScopes": [
    "string"
  ]
}

{
  "audience": "string",
  "authorizationType": "GROUP",
  "description": "string",
  "displayName": "string",
  "groupsClaim": "string",
  "idpType": "WORKFORCE",
  "issuerUri": "urn:idp:default",
  "protocol": "SAML",
  "userClaim": "string"
}

Response examples (200)

{
  "associatedOrgs": [
    {
      "dataAccessIdentityProviderIds": [
        "string"
      ],
      "domainAllowList": [
        "string"
      ],
      "domainRestrictionEnabled": true,
      "identityProviderId": "string",
      "orgId": "32b6e34b3d91647abb20e7b8",
      "postAuthRoleGrants": [
        "ORG_OWNER"
      ],
      "roleMappings": [
        {
          "externalGroupName": "string",
          "id": "32b6e34b3d91647abb20e7b8",
          "roleAssignments": [
            {
              "groupId": "32b6e34b3d91647abb20e7b8",
              "orgId": "32b6e34b3d91647abb20e7b8",
              "role": "ORG_OWNER"
            }
          ]
        }
      ],
      "userConflicts": [
        {
          "emailAddress": "hello@example.com",
          "federationSettingsId": "32b6e34b3d91647abb20e7b8",
          "firstName": "string",
          "lastName": "string",
          "userId": "32b6e34b3d91647abb20e7b8"
        }
      ]
    }
  ],
  "audience": "string",
  "authorizationType": "GROUP",
  "createdAt": "2025-05-04T09:42:00Z",
  "description": "string",
  "displayName": "string",
  "groupsClaim": "string",
  "id": "32b6e34b3d91647abb20e7b8",
  "idpType": "WORKFORCE",
  "issuerUri": "string",
  "oktaIdpId": "string",
  "protocol": "SAML",
  "updatedAt": "2025-05-04T09:42:00Z",
  "userClaim": "string",
  "associatedDomains": [
    "string"
  ],
  "clientId": "string",
  "requestedScopes": [
    "string"
  ]
}

{
  "associatedOrgs": [
    {
      "dataAccessIdentityProviderIds": [
        "string"
      ],
      "domainAllowList": [
        "string"
      ],
      "domainRestrictionEnabled": true,
      "identityProviderId": "string",
      "orgId": "32b6e34b3d91647abb20e7b8",
      "postAuthRoleGrants": [
        "ORG_OWNER"
      ],
      "roleMappings": [
        {
          "externalGroupName": "string",
          "id": "32b6e34b3d91647abb20e7b8",
          "roleAssignments": [
            {
              "groupId": "32b6e34b3d91647abb20e7b8",
              "orgId": "32b6e34b3d91647abb20e7b8",
              "role": "ORG_OWNER"
            }
          ]
        }
      ],
      "userConflicts": [
        {
          "emailAddress": "hello@example.com",
          "federationSettingsId": "32b6e34b3d91647abb20e7b8",
          "firstName": "string",
          "lastName": "string",
          "userId": "32b6e34b3d91647abb20e7b8"
        }
      ]
    }
  ],
  "audience": "string",
  "authorizationType": "GROUP",
  "createdAt": "2025-05-04T09:42:00Z",
  "description": "string",
  "displayName": "string",
  "groupsClaim": "string",
  "id": "32b6e34b3d91647abb20e7b8",
  "idpType": "WORKFORCE",
  "issuerUri": "string",
  "oktaIdpId": "string",
  "protocol": "SAML",
  "updatedAt": "2025-05-04T09:42:00Z",
  "userClaim": "string"
}

Response examples (400)

{
  "error": 400,
  "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.",
  "reason": "Bad Request",
  "errorCode": "VALIDATION_ERROR"
}

Response examples (401)

{
  "error": 401,
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "reason": "Unauthorized",
  "errorCode": "NOT_ORG_GROUP_CREATOR"
}

Response examples (403)

{
  "error": 403,
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "reason": "Forbidden",
  "errorCode": "CANNOT_CHANGE_GROUP_NAME"
}

Response examples (404)

{
  "error": 404,
  "detail": "(This is just an example, the exception may not be related to this endpoint) Cannot find resource AWS",
  "reason": "Not Found",
  "errorCode": "RESOURCE_NOT_FOUND"
}

Response examples (500)

{
  "error": 500,
  "detail": "(This is just an example, the exception may not be related to this endpoint)",
  "reason": "Internal Server Error",
  "errorCode": "UNEXPECTED_ERROR"
}