POST /api/v1/idps

Creates a new Identity Provider integration.

SAML 2.0 Identity Provider

You must first add the IdP's signature certificate to the IdP key store before you can add a SAML 2.0 IdP with a kid credential reference.

Don't use fromURI to automatically redirect a user to a particular app after successfully authenticating with a third-party IdP. Instead, use SAML deep links. Using fromURI isn't tested or supported. For more information about using deep links when signing users in using an SP-initiated flow, see Understanding SP-Initiated Login flow.

Use SAML deep links to automatically redirect the user to an app after successfully authenticating with a third-party IdP. To use deep links, assemble these three parts into a URL:

SP ACS URL
For example: https://${yourOktaDomain}/sso/saml2/:idpId
The app to which the user is automatically redirected after successfully authenticating with the IdP
For example: /app/:app-location/:appId/sso/saml
Optionally, if the app is an outbound SAML app, you can specify the relayState passed to it.
For example: ?RelayState=:anyUrlEncodedValue

The deep link for the above three parts is:
https://${yourOktaDomain}/sso/saml2/:idpId/app/:app-location/:appId/sso/saml?RelayState=:anyUrlEncodedValue

Smart Card X509 Identity Provider

You must first add the IdP's server certificate to the IdP key store before you can add a Smart Card X509 IdP with a kid credential reference. You need to upload the whole trust chain as a single key using the Key Store API. Depending on the information stored in the smart card, select the proper template idpuser.subjectAltNameEmail or idpuser.subjectAltNameUpn.

Servers

https://{yourOktaDomain}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name Type Required Description

id

String

Unique key for the IdP

_links

Object

Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.

created

String

Timestamp when the object was created

issuerMode

String

Indicates whether Okta uses the original Okta org domain URL or a custom domain URL in the request to the social IdP

Possible values:

"CUSTOM_URL"
"DYNAMIC"
"ORG_URL"

Default value: "DYNAMIC"

name

String

Unique name for the IdP

properties

Object

The properties in the Identity Provider Properties object vary depending on the IdP type

properties.aalValue

String

The authentication assurance level (AAL) value for the Login.gov IdP. See Add a Login.gov IdP. Applies to LOGINGOV and LOGINGOV_SANDBOX IdP types.

properties.additionalAmr[]

Array

The additional Assurance Methods References (AMR) values for Smart Card IdPs. Applies to X509 IdP type.

properties.ialValue

String

The type of identity verification (IAL) value for the Login.gov IdP. See Add a Login.gov IdP. Applies to LOGINGOV and LOGINGOV_SANDBOX IdP types.

protocol Object No

protocol.scopes[] Array No

protocol.relayState Object No

protocol.relayState.format

String

Possible values:

"FROM_URL"
"OPAQUE"

protocol.credentials Object No

protocol.credentials.client Object No

protocol.credentials.client.pkce_required

Boolean

Require Proof Key for Code Exchange (PKCE) for additional verification

protocol.credentials.client.client_id String No

protocol.credentials.client.client_secret String No

protocol.credentials.signing Object No

protocol.credentials.signing.kid String No

protocol.credentials.trust Object No

protocol.credentials.trust.issuer String No

protocol.credentials.trust.kid String No

protocol.credentials.trust.revocationCacheLifetime Integer No

protocol.credentials.trust.revocation

String

Possible values:

"OCSP"
"DELTA_CRL"
"CRL"

protocol.credentials.trust.audience String No

protocol.issuer Object No

protocol.issuer.destination String No

protocol.issuer.url String No

protocol.issuer.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.issuer.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.type

String

Possible values:

"OAUTH2"
"SAML2"
"OIDC"
"MTLS"

protocol.settings Object No

protocol.settings.nameFormat String No

protocol.algorithms Object No

protocol.algorithms.response Object No

protocol.algorithms.response.signature Object No

protocol.algorithms.response.signature.algorithm String No

protocol.algorithms.response.signature.scope

String

Possible values:

"ANY"
"REQUEST"
"RESPONSE"
"TOKEN"
"NONE"

protocol.algorithms.request Object No

protocol.algorithms.request.signature Object No

protocol.algorithms.request.signature.algorithm String No

protocol.algorithms.request.signature.scope

String

Possible values:

"ANY"
"REQUEST"
"RESPONSE"
"TOKEN"
"NONE"

protocol.endpoints Object No

protocol.endpoints.sso Object No

protocol.endpoints.sso.destination String No

protocol.endpoints.sso.url String No

protocol.endpoints.sso.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.sso.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.userInfo Object No

protocol.endpoints.userInfo.destination String No

protocol.endpoints.userInfo.url String No

protocol.endpoints.userInfo.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.userInfo.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.acs Object No

protocol.endpoints.acs.destination String No

protocol.endpoints.acs.url String No

protocol.endpoints.acs.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.acs.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.authorization Object No

protocol.endpoints.authorization.destination String No

protocol.endpoints.authorization.url String No

protocol.endpoints.authorization.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.authorization.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.token Object No

protocol.endpoints.token.destination String No

protocol.endpoints.token.url String No

protocol.endpoints.token.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.token.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.metadata Object No

protocol.endpoints.metadata.destination String No

protocol.endpoints.metadata.url String No

protocol.endpoints.metadata.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.metadata.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.slo Object No

protocol.endpoints.slo.destination String No

protocol.endpoints.slo.url String No

protocol.endpoints.slo.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.slo.type

String

Possible values:

"ORG"
"INSTANCE"

protocol.endpoints.jwks Object No

protocol.endpoints.jwks.destination String No

protocol.endpoints.jwks.url String No

protocol.endpoints.jwks.binding

String

Possible values:

"HTTP-POST"
"HTTP-REDIRECT"

protocol.endpoints.jwks.type

String

Possible values:

"ORG"
"INSTANCE"

type

String

The Identity Provider object's type property identifies the social or enterprise Identity Provider used for authentication. Each Identity Provider uses a specific protocol, therefore the protocol property must correspond with the IdP type. If the protocol is OAuth 2.0-based, the Protocol object's scopes property must also correspond with the scopes supported by the IdP type. For policy actions supported by each IdP type, see IdP type policy actions.

Type	Description	Corresponding protocol	Corresponding protocol scopes
`AMAZON`	Amazon as the Identity Provider	OpenID Connect	`profile`, `profile:user_id`
`APPLE`	Apple as the Identity Provider	OpenID Connect	`names`, `email`, `openid`
`DISCORD`	Discord as the Identity Provider	OAuth 2.0	`identify`, `email`
`FACEBOOK`	Facebook as the Identity Provider	OAuth 2.0	`public_profile`, `email`
`GITHUB`	GitHub as the Identity Provider	OAuth 2.0	`user`
`GITLAB`	GitLab as the Identity Provider	OpenID Connect	`openid`, `read_user`, `profile`, `email`
`GOOGLE`	Google as the Identity Provider	OpenID Connect	`openid`, `email`, `profile`
`LINKEDIN`	LinkedIn as the Identity Provider	OAuth 2.0	`r_emailaddress`, `r_liteprofile`
`LOGINGOV`	Login.gov as the Identity Provider	OpenID Connect	`email`, `profile`, `profile:name`
`LOGINGOV_SANDBOX`	Login.gov's identity sandbox as the Identity Provider	OpenID Connect	`email`, `profile`, `profile:name`
`MICROSOFT`	Microsoft Enterprise SSO as the Identity Provider	OpenID Connect	`openid`, `email`, `profile`, `https://graph.microsoft.com/User.Read`
`OIDC`	IdP provider that supports OpenID Connect	OpenID Connect	`openid`, `email`, `profile`
`PAYPAL`	Paypal as the Identity Provider	OpenID Connect	`openid`, `email`, `profile`
`PAYPAL_SANDBOX`	Paypal Sandbox as the Identity Provider	OpenID Connect	`openid`, `email`, `profile`
`SALESFORCE`	SalesForce as the Identity Provider	OAuth 2.0	`id`, `email`, `profile`
`SAML2`	Enterprise IdP provider that supports the SAML 2.0 Web Browser SSO Profile	SAML 2.0
`SPOTIFY`	Spotify as the Identity Provider	OpenID Connect	`user-read-email`, `user-read-private`
`X509`	Smart Card IdP	Mutual TLS
`XERO`	Xero as the Identity Provider	OpenID Connect	`openid`, `profile`, `email`
`YAHOO`	Yahoo as the Identity Provider	OpenID Connect	`openid`, `profile`, `email`
`YAHOOJP`	Yahoo Japan as the Identity Provider	OpenID Connect	`openid`, `profile`, `email`

Possible values:

"APPLE"
"PAYPAL_SANDBOX"
"OIDC"
"GITHUB"
"XERO"
"GOOGLE"
"YAHOO"
"X509"
"FACEBOOK"
"SAML2"
"SPOTIFY"
"YAHOOJP"
"GITLAB"
"LINKEDIN"
"MICROSOFT"
"AMAZON"
"LOGINGOV"
"PAYPAL"
"SALESFORCE"
"DISCORD"
"LOGINGOV_SANDBOX"

status

String

Possible values:

"ACTIVE"
"INACTIVE"

lastUpdated

String

Timestamp when the object was last updated

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.