On this page

Identity Providers API

The Okta Identity Providers API provides operations to manage federations with external Identity Providers (IdP). For example, your app can support signing in with credentials from Apple, Facebook, Google, LinkedIn, Microsoft, an enterprise IdP using SAML 2.0, or an IdP using the OpenID Connect (OIDC) protocol.

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

Get started

Explore the Identity Providers API: Run in Postman (opens new window)

See Add and external Identity Provider for detailed IdP set up guides using the Admin Console.

Identity Provider operations

Add Identity Provider

POST /api/v1/idps

Adds an IdP to your organization. See Identity Provider type for the list of supported external IdPs.

Request parameters
Parameter Description Param Type DataType Required
idp IdP settings Body Identity Provider TRUE
Response parameters

The created Identity Provider

Request examples

See Identity Provider type for a list of all the supported external IdPs.

Add Generic OpenID Connect Identity Provider

Adds an OIDC type IdP to your organization

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "OIDC",
  "name": "Example OpenID Connect IdP",
  "protocol": {
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "HS256",
          "scope": "REQUEST"
        }
      },
    },
    "endpoints": {
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      },
      "authorization": {
        "binding": "HTTP-REDIRECT",
        "url": "https://idp.example.com/authorize"
      },
      "token": {
        "binding": "HTTP-POST",
        "url": "https://idp.example.com/token"
      },
      "userInfo": {
        "binding": "HTTP-REDIRECT",
        "url": "https://idp.example.com/userinfo"
      },
      "jwks": {
        "binding": "HTTP-REDIRECT",
        "url": "https://idp.example.com/keys"
      }
    },
    "scopes": [
      "openid",
      "profile",
      "email"
    ],
    "type": "OIDC",
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
        "pkce_required": "true"
      }
    },
    "issuer": {
      "url": "https://idp.example.com"
    }
  },
  "policy": {
    "accountLink": {
      "action": "AUTO",
      "filter": null
    },
    "provisioning": {
      "action": "AUTO",
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      },
      "groups": {
        "action": "NONE"
      }
    },
    "mapAMRClaims": false,
    "maxClockSkew": 120000,
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.email"
      },
      "matchType": "USERNAME"
    }
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
    "id": "0oaulob4BFVa4zQvt0g3",
    "type": "OIDC",
    "name": "Example OpenID Connect IdP",
    "status": "ACTIVE",
    "created": "2019-02-07T20:07:47.000Z",
    "lastUpdated": "2019-02-07T20:07:47.000Z",
    "protocol": {
        "type": "OIDC",
        "endpoints": {
            "authorization": {
                "url": "https://idp.example.com/authorize",
                "binding": "HTTP-REDIRECT"
            },
            "token": {
                "url": "https://idp.example.com/token",
                "binding": "HTTP-POST"
            },
            "userInfo": {
                "url": "https://idp.example.com/userinfo",
                "binding": "HTTP-REDIRECT"
            },
            "jwks": {
                "url": "https://idp.example.com/keys",
                "binding": "HTTP-REDIRECT"
            }
        },
        "algorithms": {
          "request": {
            "signature": {
              "algorithm": "HS256",
              "scope": "REQUEST"
            }
          }
        },
        "scopes": [
            "openid"
        ],
        "issuer": {
            "url": "https://idp.example.com"
        },
        "credentials": {
            "client": {
                "client_id": "your-client-id",
                "client_secret": "your-client-secret",
                "pkce_required": "true"
            }
        }
    },
    "policy": {
        "provisioning": {
            "action": "AUTO",
            "profileMaster": false,
            "groups": {
                "action": "NONE"
            },
            "conditions": {
                "deprovisioned": {
                    "action": "NONE"
                },
                "suspended": {
                    "action": "NONE"
                }
            }
        },
        "accountLink": {
            "filter": null,
            "action": "AUTO"
        },
        "subject": {
            "userNameTemplate": {
                "template": "idpuser.email"
            },
            "filter": null,
            "matchType": "USERNAME",
            "matchAttribute": null
        },
        "mapAMRClaims": false,
        "maxClockSkew": 0
    },
    "_links": {
        "authorize": {
            "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oaulob4BFVa4zQvt0g3&client_id={clientId}&response_type={responseType}&response_mode={responseMode}&scope={scopes}&redirect_uri={redirectUri}&state={state}&nonce={nonce}",
            "templated": true,
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "clientRedirectUri": {
            "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}

Add SAML 2.0 Identity Provider

Adds a SAML2 type IdP to your organization

Notes: 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 and not supported. For more information about using deep links when signing users in using an SP-initiated flow, see Understanding SP-Initiated Login flow.

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "SAML2",
  "name": "Example SAML IdP",
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "sso": {
        "url": "https://idp.example.com",
        "binding": "HTTP-POST",
        "destination": "https://idp.example.com"
      },
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      }
    },
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "REQUEST"
        }
      },
      "response": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "ANY"
        }
      }
    },
    "credentials": {
      "trust": {
        "issuer": "https://idp.example.com",
        "audience": "http://www.okta.com/123",
        "kid": "your-key-id"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "saml.subjectNameId"
      },
      "format": [
          "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
      ],
      "filter": "(\\S+@example\\.com)",
      "matchType": "USERNAME"
    }
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
  "id": "0oa62bc8wppPw0UGr0h7",
  "type": "SAML2",
  "name": "Example SAML IdP",
  "status": "ACTIVE",
  "created": "2016-03-24T23:14:54.000Z",
  "lastUpdated": "2016-03-24T23:14:54.000Z",
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "sso": {
        "url": "https://idp.example.com",
        "binding": "HTTP-POST",
        "destination": "https://idp.example.com"
      },
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      }
    },
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "REQUEST"
        }
      },
      "response": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "ANY"
        }
      }
    },
    "settings": {
      "nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
    },
    "credentials": {
      "trust": {
        "issuer": "https://idp.example.com",
        "audience": "http://www.okta.com/123",
        "kid": "your-key-id"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "saml.subjectNameId"
      },
      "filter": "(\\S+@example\\.com)",
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "metadata": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/metadata.xml",
      "type": "application/xml",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "acs": {
      "href": "https://{yourOktaDomain}/sso/saml2/0oa62bc8wppPw0UGr0h7",
      "type": "application/xml",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "users": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/users",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

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

Add Apple Identity Provider

Adds an Apple type IdP to your organization

Request example

Note: The key is truncated for brevity.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "APPLE",
  "name": "Apple Identity Provider",
  "protocol": {
    "type": "OIDC",
    "scopes": ["openid", "email", "name"],
    "credentials": {
      "client": {
        "client_id": "your-client-id"
      },
      "signing": {
        "privateKey": "MIGTAgEAMBM........Cb9PnybCnzDv+3cWSGWqpAIsQQZ",
        "kid": "test key id",
        "teamId": "test team id"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.email"
      },
      "matchType": "USERNAME"
    }
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example

Note: The key is truncated for brevity.

{
  "id": "0oa18hsHsG3boVejU0g4",
  "type": "APPLE",
  "issuerMode": "ORG_URL",
  "name": "Apple Identity Provider",
  "status": "ACTIVE",
  "created": "2020-06-05T20:57:51.000Z",
  "lastUpdated": "2020-06-05T20:57:51.000Z",
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://appleid.apple.com/auth/authorize",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://appleid.apple.com/auth/token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "openid",
      "email",
      "name"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id"
      },
      "signing": {
        "teamId": "test team id",
        "privateKey": "MIGTAgEAMBM........Cb9PnybCnzDv+3cWSGWqpAIsQQZ",
        "kid": "test key id"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.email"
      },
      "filter": null,
      "matchType": "USERNAME",
      "matchAttribute": null
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa18hsHsG3boVejU0g4&client_id={clientId}&response_type={responseType}&response_mode={responseMode}&scope={scopes}&redirect_uri=${redirectUri}&state={state}&nonce={nonce}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Add Facebook Identity Provider

Adds a FACEBOOK type IdP to your organization

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "FACEBOOK",
  "name": "Facebook",
  "protocol": {
    "type": "OAUTH2",
    "scopes": [
      "public_profile",
      "email"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
  "id": "0oa62b57p7c8PaGpU0h7",
  "type": "FACEBOOK",
  "name": "Facebook",
  "status": "ACTIVE",
  "created": "2016-03-24T23:18:27.000Z",
  "lastUpdated": "2016-03-24T23:18:27.000Z",
  "protocol": {
    "type": "OAUTH2",
    "endpoints": {
      "authorization": {
        "url": "https://www.facebook.com/dialog/oauth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://graph.facebook.com/v2.5/oauth/access_token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "public_profile",
      "email"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62b57p7c8PaGpU0h7&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Add Google Identity Provider

Adds a Google type IdP to your organization

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "GOOGLE",
  "name": "Google",
  "protocol": {
    "type": "OAUTH2",
    "scopes": [
      "profile",
      "email",
      "openid"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
  "id": "0oa62bfdiumsUndnZ0h7",
  "type": "GOOGLE",
  "name": "Google",
  "status": "ACTIVE",
  "created": "2016-03-24T23:21:49.000Z",
  "lastUpdated": "2016-03-24T23:21:49.000Z",
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://accounts.google.com/o/oauth2/auth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://www.googleapis.com/oauth2/v3/token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "profile",
      "email",
      "openid"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdiumsUndnZ0h7&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Add LinkedIn Identity Provider

Adds a LINKEDIN type IdP to your organization

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "LINKEDIN",
  "name": "LinkedIn",
  "protocol": {
    "type": "OAUTH2",
    "scopes": [
      "r_basicprofile",
      "r_emailaddress"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
  "id": "0oa62bfdjnK55Z5x80h7",
  "type": "LINKEDIN",
  "name": "LinkedIn",
  "status": "ACTIVE",
  "created": "2016-03-24T23:23:59.000Z",
  "lastUpdated": "2016-03-24T23:23:59.000Z",
  "protocol": {
    "type": "OAUTH2",
    "endpoints": {
      "authorization": {
        "url": "https://www.linkedin.com/uas/oauth2/authorization",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://www.linkedin.com/uas/oauth2/accessToken",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "r_basicprofile",
      "r_emailaddress"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdjnK55Z5x80h7&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Add Microsoft Identity Provider

Adds a Microsoft type IdP to your organization

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "MICROSOFT",
  "name": "Microsoft",
  "protocol": {
    "type": "OIDC",
    "scopes": ["openid", "email", "profile", "https://graph.microsoft.com/User.Read"],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
  "id": "0oajmvdFawBih4gey0g3",
  "type": "MICROSOFT",
  "name": "Microsoft",
  "status": "ACTIVE",
  "created": "2016-03-29T16:47:36.000Z",
  "lastUpdated": "2016-03-29T16:47:36.000Z",
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "openid",
      "email",
      "profile",
      "https://graph.microsoft.com/User.Read"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oajmvdFawBih4gey0g3&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Add Smart Card Identity Provider

Adds a Smart Card X509 type IdP to your organization

Request example

Notes: 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.

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "type": "X509",
  "status": "ACTIVE",
  "name": "Smart Card IDP Name",
  "properties": {
    "additionalAmr": [
      "sc",
      "hwk",
      "pin",
      "mfa",
    ]
  },
  "protocol": {
    "type": "MTLS",
    "credentials": {
      "trust": {
        "revocation": "CRL",
        "revocationCacheLifetime": 2880,
        "issuer": "your-issuer",
        "kid": "your-kid"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action":"DISABLED"
      }
    },
    "mapAMRClaims": false,
    "maxClockSkew":120000,
    "subject": {
      "matchType": "EMAIL",
      "matchAttribute": "",
      "userNameTemplate": {
        "template": "idpuser.subjectAltNameEmail"
      }
    }
  }
}' "https://${yourOktaDomain}/api/v1/idps"
Response example
{
  "id": "0oa6jxasyhwM2ZHJh0g4",
  "type": "X509",
  "name": "Smart Card IDP Name",
  "status": "ACTIVE",
  "created": "2020-01-07T00:19:27.000Z",
  "lastUpdated": "2020-01-07T00:19:27.000Z",
  "properties": {
    "additionalAmr": [
      "sc",
      "hwk",
      "pin",
      "mfa",
    ]
  },
  "protocol": {
    "type": "MTLS",
    "endpoints": {
      "sso": {
        "url": "https://{yourOktaDomain}.okta.com/login/cert"
      }
    },
    "credentials": {
      "trust": {
        "issuer": "CN=Test Smart Card, OU=Test OU, O=Test O, C=US",
        "audience": null,
        "kid":"45dec5ff-8cdc-48c0-85fe-a4869f1753dc",
        "revocation":"CRL",
        "revocationCacheLifetime":2880
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "DISABLED",
      "profileMaster": false,
      "groups": null
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.subjectAltNameEmail"
      },
      "filter": null,
      "matchType": "EMAIL",
      "matchAttribute": null
    },
    "mapAMRClaims": false,
    "maxClockSkew":120000
  },
  "_links": {
    "deactivate": {
      "href": "https://{yourOktaDomain}.okta.com/api/v1/idps/0oa6jxasyhwM2ZHJh0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "users": {
      "href": "https://{yourOktaDomain}.okta.com/api/v1/idps/0oa6jxasyhwM2ZHJh0g4/users",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "keys": {
      "href":"https://{yourOktaDomain}.okta.com/api/v1/idps/credentials/keys/45dec5ff-8cdc-48c0-85fe-a4869f1753dc",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}

Get Identity Provider

GET /api/v1/idps/${idpId}

Fetches an IdP by id

Request parameters
Parameter Description Param Type DataType Required
idpId id of an IdP URL String TRUE
Response parameters

Identity Provider

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oa62bfdjnK55Z5x80h7"
Response example
{
  "id": "0oa62bfdjnK55Z5x80h7",
  "type": "LINKEDIN",
  "name": "LinkedIn",
  "status": "ACTIVE",
  "created": "2016-03-24T23:23:59.000Z",
  "lastUpdated": "2016-03-24T23:23:59.000Z",
  "protocol": {
    "type": "OAUTH2",
    "endpoints": {
      "authorization": {
        "url": "https://www.linkedin.com/uas/oauth2/authorization",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://www.linkedin.com/uas/oauth2/accessToken",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "r_basicprofile",
      "r_emailaddress"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdjnK55Z5x80h7&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

List Identity Providers

GET /api/v1/idps

Enumerates IdPs in your organization with pagination. A subset of IdPs can be returned that match a supported filter expression or query.

Request parameters
Parameter Description Param Type DataType Required Default
after Specifies the pagination cursor for the next page of IdPs Query String FALSE
limit Specifies the number of IdP results in a page Query Number FALSE 20
q Searches the name property of IdPs for matching value Query String FALSE
type Filters IdPs by type Query String FALSE

Parameter details

  • Treat the after cursor as an opaque value. You can obtain it through the next link relationship. See Pagination.
  • Search currently performs a startsWith match, but it should be considered an implementation detail and may change without notice in the future.
Response parameters

Array of Identity Provider

List Identity Providers with defaults

Enumerates all IdPs in your organization

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps?limit=20"
Response example
[
  {
    "id": "0oa62b57p7c8PaGpU0h7",
    "type": "FACEBOOK",
    "name": "Facebook",
    "status": "ACTIVE",
    "created": "2016-03-24T23:18:27.000Z",
    "lastUpdated": "2016-03-24T23:18:27.000Z",
    "protocol": {
      "type": "OAUTH2",
      "endpoints": {
        "authorization": {
          "url": "https://www.facebook.com/dialog/oauth",
          "binding": "HTTP-REDIRECT"
        },
        "token": {
          "url": "https://graph.facebook.com/v2.5/oauth/access_token",
          "binding": "HTTP-POST"
        }
      },
      "scopes": [
        "public_profile",
        "email"
      ],
      "credentials": {
        "client": {
          "client_id": "your-client-id",
          "client_secret": "your-client-secret"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "idpuser.userPrincipalName"
        },
        "filter": null,
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "authorize": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62b57p7c8PaGpU0h7&
            client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
            scope={scopes}&redirect_uri={redirectUri}&state={state}",
        "templated": true,
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "clientRedirectUri": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "id": "0oa62bc8wppPw0UGr0h7",
    "type": "SAML2",
    "name": "Example SAML IdP",
    "status": "ACTIVE",
    "created": "2016-03-24T23:14:54.000Z",
    "lastUpdated": "2016-03-24T23:14:54.000Z",
    "protocol": {
      "type": "SAML2",
      "endpoints": {
        "sso": {
          "url": "https://idp.example.com",
          "binding": "HTTP-POST",
          "destination": "https://idp.example.com"
        },
        "acs": {
          "binding": "HTTP-POST",
          "type": "INSTANCE"
        }
      },
      "algorithms": {
        "request": {
          "signature": {
            "algorithm": "SHA-256",
            "scope": "REQUEST"
          }
        },
        "response": {
          "signature": {
            "algorithm": "SHA-256",
            "scope": "ANY"
          }
        }
      },
      "settings": {
        "nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
      },
      "credentials": {
        "trust": {
          "issuer": "https://idp.example.com",
          "audience": "http://www.okta.com/123",
          "kid": "your-key-id"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "saml.subjectNameId"
        },
        "filter": "(\\S+@example\\.com)",
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "metadata": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/metadata.xml",
        "type": "application/xml",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "acs": {
        "href": "https://{yourOktaDomain}/sso/saml2/0oa62bc8wppPw0UGr0h7",
        "type": "application/xml",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      },
      "users": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/users",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "id": "0oa62bfdiumsUndnZ0h7",
    "type": "GOOGLE",
    "name": "Google",
    "status": "ACTIVE",
    "created": "2016-03-24T23:21:49.000Z",
    "lastUpdated": "2016-03-24T23:21:49.000Z",
    "protocol": {
      "type": "OIDC",
      "endpoints": {
        "authorization": {
          "url": "https://accounts.google.com/o/oauth2/auth",
          "binding": "HTTP-REDIRECT"
        },
        "token": {
          "url": "https://www.googleapis.com/oauth2/v3/token",
          "binding": "HTTP-POST"
        }
      },
      "scopes": [
        "profile",
        "email",
        "openid"
      ],
      "credentials": {
        "client": {
          "client_id": "your-client-id",
          "client_secret": "your-client-secret"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "idpuser.userPrincipalName"
        },
        "filter": null,
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "authorize": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdiumsUndnZ0h7&
            client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
            scope={scopes}&redirect_uri={redirectUri}&state={state}",
        "templated": true,
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "clientRedirectUri": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "id": "0oa62bfdjnK55Z5x80h7",
    "type": "LINKEDIN",
    "name": "LinkedIn",
    "status": "ACTIVE",
    "created": "2016-03-24T23:23:59.000Z",
    "lastUpdated": "2016-03-24T23:23:59.000Z",
    "protocol": {
      "type": "OAUTH2",
      "endpoints": {
        "authorization": {
          "url": "https://www.linkedin.com/uas/oauth2/authorization",
          "binding": "HTTP-REDIRECT"
        },
        "token": {
          "url": "https://www.linkedin.com/uas/oauth2/accessToken",
          "binding": "HTTP-POST"
        }
      },
      "scopes": [
        "r_basicprofile",
        "r_emailaddress"
      ],
      "credentials": {
        "client": {
          "client_id": "your-client-id",
          "client_secret": "your-client-secret"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "idpuser.userPrincipalName"
        },
        "filter": null,
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "authorize": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdjnK55Z5x80h7&
            client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
            scope={scopes}&redirect_uri={redirectUri}&state={state}",
        "templated": true,
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "clientRedirectUri": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "id": "0oajmvdFawBih4gey0g3",
    "type": "MICROSOFT",
    "name": "Microsoft",
    "status": "ACTIVE",
    "created": "2016-03-29T16:47:36.000Z",
    "lastUpdated": "2016-03-29T16:47:36.000Z",
    "protocol": {
      "type": "OIDC",
      "endpoints": {
        "authorization": {
          "url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
          "binding": "HTTP-REDIRECT"
        },
        "token": {
          "url": "https://login.microsoftonline.com/common/oauth2/v2.0/token",
          "binding": "HTTP-POST"
        }
      },
      "scopes": [
        "openid",
        "email",
        "profile",
        "https://graph.microsoft.com/User.Read"
      ],
      "credentials": {
        "client": {
          "client_id": "your-client-id",
          "client_secret": "your-client-secret"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "idpuser.userPrincipalName"
        },
        "filter": null,
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "authorize": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oajmvdFawBih4gey0g3&
            client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
            scope={scopes}&redirect_uri={redirectUri}&state={state}",
        "templated": true,
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "clientRedirectUri": {
        "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
      "id": "0oaulob4BFVa4zQvt0g3",
      "type": "OIDC",
      "name": "Example OpenID Connect IdP",
      "status": "ACTIVE",
      "created": "2019-02-07T20:07:47.000Z",
      "lastUpdated": "2019-02-07T20:07:47.000Z",
      "protocol": {
          "type": "OIDC",
          "endpoints": {
              "authorization": {
                  "url": "https://idp.example.com/authorize",
                  "binding": "HTTP-REDIRECT"
              },
              "token": {
                  "url": "https://idp.example.com/token",
                  "binding": "HTTP-POST"
              },
              "userInfo": {
                  "url": "https://idp.example.com/userinfo",
                  "binding": "HTTP-REDIRECT"
              },
              "jwks": {
                  "url": "https://idp.example.com/keys",
                  "binding": "HTTP-REDIRECT"
              }
          },
          "scopes": [
              "openid"
          ],
          "issuer": {
              "url": "https://idp.example.com"
          },
          "credentials": {
              "client": {
                  "client_id": "your-client-id",
                  "client_secret": "your-client-secret"
              }
          }
      },
      "policy": {
          "provisioning": {
              "action": "AUTO",
              "profileMaster": false,
              "groups": {
                  "action": "NONE"
              },
              "conditions": {
                  "deprovisioned": {
                      "action": "NONE"
                  },
                  "suspended": {
                      "action": "NONE"
                  }
              }
          },
          "accountLink": {
              "filter": null,
              "action": "AUTO"
          },
          "subject": {
              "userNameTemplate": {
                  "template": "idpuser.email"
              },
              "filter": null,
              "matchType": "USERNAME",
              "matchAttribute": null
          },
          "mapAMRClaims": false,
          "maxClockSkew": 0
      },
      "_links": {
          "authorize": {
              "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oaulob4BFVa4zQvt0g3&client_id={clientId}&response_type={responseType}&response_mode={responseMode}&scope={scopes}&redirect_uri={redirectUri}&state={state}&nonce={nonce}",
              "templated": true,
              "hints": {
                  "allow": [
                      "GET"
                  ]
              }
          },
          "clientRedirectUri": {
              "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
              "hints": {
                  "allow": [
                      "POST"
                  ]
              }
          }
      }
  },
  {
  "id": "0oa6jxasyhwM2ZHJh0g4",
  "type": "X509",
  "name": "Smart Card IDP Name",
  "status": "ACTIVE",
  "created": "2020-01-07T00:19:27.000Z",
  "lastUpdated": "2020-01-07T00:19:27.000Z",
  "properties": {
    "additionalAmr": [
      "sc",
      "hwk",
      "pin",
      "mfa",
    ]
  },
  "protocol": {
    "type": "MTLS",
    "endpoints": {
      "sso": {
        "url": "https://{yourOktaDomain}.okta.com/login/cert"
      }
    },
    "credentials": {
      "trust": {
        "issuer": "CN=Test Smart Card, OU=Test OU, O=Test O, C=US",
        "audience": null,
        "kid":"45dec5ff-8cdc-48c0-85fe-a4869f1753dc",
        "revocation":"CRL",
        "revocationCacheLifetime":2880
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "DISABLED",
      "profileMaster": false,
      "groups": null
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.subjectAltNameEmail"
      },
      "filter": null,
      "matchType": "EMAIL",
      "matchAttribute": null
    },
    "mapAMRClaims": false,
    "maxClockSkew":0
  },
  "_links": {
    "deactivate": {
      "href": "https://{yourOktaDomain}.okta.com/api/v1/idps/0oa6jxasyhwM2ZHJh0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "users": {
      "href": "https://{yourOktaDomain}.okta.com/api/v1/idps/0oa6jxasyhwM2ZHJh0g4/users",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "keys": {
      "href":"https://{yourOktaDomain}.okta.com/api/v1/idps/credentials/keys/45dec5ff-8cdc-48c0-85fe-a4869f1753dc",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    }
  }
}
]

Find Identity Providers by name

Searches for IdPs by name in your organization

Search currently performs a startsWith match, but it should be considered an implementation detail and may change without notice in the future. Exact matches are returned before partial matches.

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps?q=Example SAML&limit=10"
Response example
[
  {
    "id": "0oa62bc8wppPw0UGr0h7",
    "type": "SAML2",
    "name": "Example SAML IdP",
    "status": "ACTIVE",
    "created": "2016-03-24T23:14:54.000Z",
    "lastUpdated": "2016-03-24T23:14:54.000Z",
    "protocol": {
      "type": "SAML2",
      "endpoints": {
        "sso": {
          "url": "https://idp.example.com",
          "binding": "HTTP-POST",
          "destination": "https://idp.example.com"
        },
        "acs": {
          "binding": "HTTP-POST",
          "type": "INSTANCE"
        }
      },
      "algorithms": {
        "request": {
          "signature": {
            "algorithm": "SHA-256",
            "scope": "REQUEST"
          }
        },
        "response": {
          "signature": {
            "algorithm": "SHA-256",
            "scope": "ANY"
          }
        }
      },
      "settings": {
        "nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
      },
      "credentials": {
        "trust": {
          "issuer": "https://idp.example.com",
          "audience": "http://www.okta.com/123",
          "kid": "your-key-id"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "saml.subjectNameId"
        },
        "filter": "(\\S+@example\\.com)",
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "metadata": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/metadata.xml",
        "type": "application/xml",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "acs": {
        "href": "https://{yourOktaDomain}/sso/saml2/0oa62bc8wppPw0UGr0h7",
        "type": "application/xml",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      },
      "users": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/users",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
]

Find Identity Providers by type

Finds all IdPs with a specific type

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps?type=SAML2"
Response example
[
  {
    "id": "0oa62bc8wppPw0UGr0h7",
    "type": "SAML2",
    "name": "Example SAML IdP",
    "status": "ACTIVE",
    "created": "2016-03-24T23:14:54.000Z",
    "lastUpdated": "2016-03-24T23:14:54.000Z",
    "protocol": {
      "type": "SAML2",
      "endpoints": {
        "sso": {
          "url": "https://idp.example.com",
          "binding": "HTTP-POST",
          "destination": "https://idp.example.com"
        },
        "acs": {
          "binding": "HTTP-POST",
          "type": "INSTANCE"
        }
      },
      "algorithms": {
        "request": {
          "signature": {
            "algorithm": "SHA-256",
            "scope": "REQUEST"
          }
        },
        "response": {
          "signature": {
            "algorithm": "SHA-256",
            "scope": "ANY"
          }
        }
      },
      "settings": {
        "nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
      },
      "credentials": {
        "trust": {
          "issuer": "https://idp.example.com",
          "audience": "http://www.okta.com/123",
          "kid": "your-key-id"
        }
      }
    },
    "policy": {
      "provisioning": {
        "action": "AUTO",
        "profileMaster": true,
        "groups": {
          "action": "NONE"
        },
        "conditions": {
          "deprovisioned": {
            "action": "NONE"
          },
          "suspended": {
            "action": "NONE"
          }
        }
      },
      "accountLink": {
        "filter": null,
        "action": "AUTO"
      },
      "subject": {
        "userNameTemplate": {
          "template": "saml.subjectNameId"
        },
        "filter": "(\\S+@example\\.com)",
        "matchType": "USERNAME"
      },
      "mapAMRClaims": false,
      "maxClockSkew": 0
    },
    "_links": {
      "metadata": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/metadata.xml",
        "type": "application/xml",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "acs": {
        "href": "https://{yourOktaDomain}/sso/saml2/0oa62bc8wppPw0UGr0h7",
        "type": "application/xml",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      },
      "users": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/users",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/lifecycle/deactivate",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
]

Update Identity Provider

PUT /api/v1/idps/${idpId}

Updates the configuration for an IdP

Request parameters
Parameter Description Param Type DataType Required
id id of the IdP to update URL String TRUE
idp Updated configuration for the IdP Body Identity Provider TRUE

All properties must be specified when updating the IdP configuration. Partial updates aren't supported.

Response parameters

Updated Identity Provider

Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/${yourIdpId}"
Response example
{
  "id": "0oa62bc8wppPw0UGr0h7",
  "type": "SAML2",
  "name": "Example SAML IdP",
  "status": "INACTIVE",
  "created": null,
  "lastUpdated": "2016-03-29T21:23:45.000Z",
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "sso": {
        "url": "https://idp.example.com/saml2/sso",
        "binding": "HTTP-REDIRECT",
        "destination": "https://idp.example.com/saml2/sso"
      },
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      }
    },
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "REQUEST"
        }
      },
      "response": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "ANY"
        }
      }
    },
    "settings": {
      "nameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
    },
    "credentials": {
      "trust": {
        "issuer": "https://idp.example.com",
        "audience": "https://www.okta.com/saml2/service-provider/spCQJRNaaxs7ANqKBO7M",
        "kid": "your-key-id"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.subjectNameId"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 120000
  },
  "_links": {
    "metadata": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/metadata.xml",
      "type": "application/xml",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "acs": {
      "href": "https://{yourOktaDomain}/sso/saml2/0oa62bc8wppPw0UGr0h7",
      "type": "application/xml",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "users": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/users",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bc8wppPw0UGr0h7/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Delete Identity Provider

DELETE /api/v1/idps/${idpId}

Removes an IdP from your organization

  • All existing IdP users are unlinked with the highest order profile source taking precedence for each IdP user.
  • Unlinked users keep their existing authentication provider such as FEDERATION or SOCIAL.
Request parameters
Parameter Description Param Type Data Type Required
idpId id of the IdP to delete URL String TRUE
Response parameters

There are no response parameters.

Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/${yourIdpId}"
Response example
HTTP/1.1 204 No Content

Identity Provider lifecycle operations

Activate Identity Provider

POST /api/v1/idps/${idpId}/lifecycle/activate

Activates an inactive IdP

Request parameters
Parameter Description Param Type DataType Required
idpId id of IdP to activate URL String TRUE
Response parameters

Activated Identity Provider

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/${yourIdpId}/lifecycle/activate"
Response example
{
  "id": "0oa62bfdiumsUndnZ0h7",
  "type": "GOOGLE",
  "name": "Google",
  "status": "ACTIVE",
  "created": "2016-03-24T23:21:49.000Z",
  "lastUpdated": "2016-03-25T19:14:23.000Z",
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://accounts.google.com/o/oauth2/auth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://www.googleapis.com/oauth2/v3/token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "profile",
      "email",
      "openid"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.email"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdiumsUndnZ0h7&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Deactivate Identity Provider

POST /api/v1/idps/${idpId}/lifecycle/deactivate

Deactivates an active IdP

Request parameters
Parameter Description Param Type DataType Required
idpId id of IdP to deactivate URL String TRUE
Response parameters

Deactivated Identity Provider

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/${yourIdpId}/lifecycle/deactivate"
Response example
{
  "id": "0oa62bfdiumsUndnZ0h7",
  "type": "GOOGLE",
  "name": "Google",
  "status": "INACTIVE",
  "created": "2016-03-24T23:21:49.000Z",
  "lastUpdated": "2016-03-25T19:16:53.000Z",
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://accounts.google.com/o/oauth2/auth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://www.googleapis.com/oauth2/v3/token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "profile",
      "email",
      "openid"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62bfdiumsUndnZ0h7&
      client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
      scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Identity Provider Transaction operations

Note: This is a Deprecated feature.

Operations for Just-In-Time (JIT) provisioning or account linking with a callout action (webhook)

All Transaction operations require a Transaction ID that is obtained as part of the authentication call.

Use callout actions when you need to retrieve information from the profile of a user when you link or create them, or to perform other tasks that must be done before the link or create is completed.

Before you can use Transaction operations, set up the following:

  1. Add or create an app in Okta with settings that support callout:

    • Allowed grant types must include one or more Client acting on behalf of a user options selected.
  2. Configure a social IdP with settings that support callout:

    • Be sure to complete the setup instructions in the View Setup Instructions link.
    • Select appropriate scopes for the client that you configured in the previous step and for the IdP as described in the View Setup Instructions.
    • In the Show Advanced Settings link, be sure that you have either the Account Link Policy or the Provisioning Policy set to Callout.

After your IdP and app are set up, you can issue an authentication request and capture the Transaction ID to verify your setup. The following example shows a request for an ID token, which is typically a simple request:

  https://${yourOktaDomain}/oauth2/v1/authorize?
  idp=0oae5emt1lCVpXD2b0h7&
  client_id=B6YnDUIpt6Oq354YYaNR&
  response_type=id_token&
  response_mode=fragment&
  scope=openid&
  redirect_uri=https://httpbin.org/get&state=state&nonce=nonce

The response contains a Transaction ID. You can then use the Transaction ID to exercise the endpoints in this section. Unfinished or uncanceled transactions end after about ten minutes.

If you aren't receiving a Transaction ID, check that:

  • The user that you're adding with JIT or linking doesn't exist in the app. If they do, deactivate and delete.
  • You don't have any sessions open for the IdP or the Okta org for the app.

Get Identity Provider Transaction

GET /api/v1/idps/tx/${transactionId}

Fetches an IdP Transaction by id

You must use a CALLOUT action for user provisioning or account linking to obtain an IdP Transaction id.

Request parameters
Parameter Description Param Type DataType Required
transactionId id of an IdP Transaction URL String TRUE
Response parameters

Identity Provider Transaction

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3"
Response example
{
  "id": "satvklBYyJmwa6qOg0g3",
  "status": "ACCOUNT_JIT",
  "expiresAt": "2016-01-03T23:52:58.000Z",
  "created": "2016-01-03T23:44:38.000Z",
  "idp": {
    "id": "0oabmluDNh2JZi8lt0g4",
    "name": "Facebook",
    "type": "FACEBOOK"
  },
  "context": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko)
        Chrome/47.0.2526.106 Safari/537.36",
    "ipAddress": "127.0.0.1"
  },
  "_links": {
    "source": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/source"
    },
    "target": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/target"
    },
    "cancel": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "provision": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/lifecycle/provision",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Get source IdP User for IdP Transaction

GET /api/v1/idps/tx/${transactionId}/source

Fetches the source IdP User for a Transaction

Request parameters
Parameter Description Param Type DataType Required
transactionId id of an IdP Transaction URL String TRUE
Response parameters

Identity Provider User

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/source"
Response example
{
  "externalId": "1437424479920471",
  "profile": {
    "middleName": null,
    "lastName": "Zuckersky",
    "email": "mark_drvbrjr_zuckersky@tfbnw.net",
    "displayName": "Mark Zuckersky",
    "firstName": "Mark",
    "profile": "https://www.facebook.com/app_scoped_user_id/1437424479920471/"
  },
  "_links": {
    "idp": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oabmluDNh2JZi8lt0g4"
    }
  }
}

Get target User for IdP provision Transaction

GET /api/v1/idps/tx/${transactionId}/target

Fetches the target transformed Okta User Profile for a Just-In-Time (JIT) provisioning Transaction

Request parameters
Parameter Description Param Type DataType Required
transactionId id of an IdP Transaction URL String TRUE
Response parameters

Transformed Okta User Profile

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/source"
Response example
{
  "profile": {
    "middleName": null,
    "streetAddress": null,
    "lastName": "Zuckersky",
    "secondEmail": null,
    "postAddress": null,
    "state": null,
    "countryCode": null,
    "city": null,
    "profileUrl": "https://www.facebook.com/app_scoped_user_id/1437424479920471/",
    "primaryPhone": null,
    "mobilePhone": null,
    "email": "mark_drvbrjr_zuckersky@tfbnw.net",
    "zipCode": null,
    "login": "mark_drvbrjr_zuckersky@tfbnw.net",
    "displayName": "Mark Zuckersky",
    "firstName": "Mark",
    "typeId": null
  }
}

GET /api/v1/idps/tx/${transactionId}/users

Enumerates the candidate Okta Users for an account link Transaction

Link candidates are determined by the IdP's account link policy and subject policy.

Request parameters
Parameter Description Param Type DataType Required
transactionId id of an IdP Transaction URL String TRUE
Response parameters

Array of Okta User

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/users"
Response example
[
  {
    "id": "00uc8wfZSNWKlFGZa0g4",
    "status": "ACTIVE",
    "created": "2016-01-03T23:55:34.000Z",
    "activated": "2016-01-03T23:55:38.000Z",
    "statusChanged": "2016-01-03T23:55:38.000Z",
    "lastLogin": null,
    "lastUpdated": "2016-01-03T23:55:38.000Z",
    "passwordChanged": null,
    "profile": {
      "login": "mark_drvbrjr_zuckersky@tfbnw.net",
      "mobilePhone": null,
      "email": "mark_drvbrjr_zuckersky@tfbnw.net",
      "secondEmail": null,
      "firstName": "Mark",
      "lastName": "Zuckersky",
      "profileUrl": "https://www.facebook.com/app_scoped_user_id/1437424479920471/",
      "displayName": "Mark Zuckersky"
    },
    "credentials": {
      "provider": {
        "type": "SOCIAL",
        "name": "SOCIAL"
      }
    },
    "_links": {
      "suspend": {
        "href": "https://{yourOktaDomain}/api/v1/users/00uc8wfZSNWKlFGZa0g4/lifecycle/suspend",
        "method": "POST"
      },
      "resetPassword": {
        "href": "https://{yourOktaDomain}/api/v1/users/00uc8wfZSNWKlFGZa0g4/lifecycle/reset_password",
        "method": "POST"
      },
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/users/00uc8wfZSNWKlFGZa0g4"
      },
      "changeRecoveryQuestion": {
        "href": "https://{yourOktaDomain}/api/v1/users/00uc8wfZSNWKlFGZa0g4/credentials/change_recovery_question",
        "method": "POST"
      },
      "deactivate": {
        "href": "https://{yourOktaDomain}/api/v1/users/00uc8wfZSNWKlFGZa0g4/lifecycle/deactivate",
        "method": "POST"
      },
      "confirm": {
        "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/lifecycle/confirm/00uc8wfZSNWKlFGZa0g4",
        "method": "POST"
      }
    }
  }
]

Provision IdP User

POST /api/v1/idps/tx/${transactionId}/lifecycle/provision

Provisions an IdP User as a new Okta User

Request parameters
Parameter Description Param Type DataType Required Default
profile profile for the Okta User Body Okta User Profile object FALSE UD transformed Okta user profile
transactionId id of an IdP Transaction URL String TRUE
Response parameters

Identity Provider Transaction

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "userType": "Social"
  }
}' "https://${yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/lifecycle/provision"
Response example
{
  "id": "satvkokI9JsOxqsjz0g3",
  "status": "SUCCESS",
  "sessionToken": "20111ItcRRtx_HOKguQRqx6YIeFL3L6cQhpqSCvLOD-fpj-3K53aqXN",
  "expiresAt": "2016-01-04T02:40:43.000Z",
  "created": "2016-01-04T02:32:23.000Z",
  "idp": {
    "id": "0oabmluDNh2JZi8lt0g4",
    "name": "Facebook",
    "type": "FACEBOOK"
  },
  "context": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko)
        Chrome/47.0.2526.106 Safari/537.36",
    "ipAddress": "127.0.0.1"
  },
  "_links": {
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/finish",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

POST /api/v1/idps/tx/${transactionId}/lifecycle/confirm/${userId}

Links an IdP User to an existing Okta User

Request parameters
Parameter Description Param Type DataType Required
profile profile for the Okta User Body Okta User Profile object FALSE
transactionId id of an IdP Transaction URL String TRUE
userId id of an Okta User link candidate URL String TRUE
Response parameters

Identity Provider Transaction

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "profile": {
    "userType": "Social"
  }
}' "https://${yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/lifecycle/confirm/00uc8ydZUPiwS2Xud0g4"
Response example
{
  "id": "satvkokI9JsOxqsjz0g3",
  "status": "SUCCESS",
  "sessionToken": "20111FLDl04JoQdl-NJOB9A6HosTSuHtQQUmCBhdEvnE4XEInod0Sg_",
  "expiresAt": "2016-01-04T02:53:13.000Z",
  "created": "2016-01-04T02:44:53.000Z",
  "idp": {
    "id": "0oabmluDNh2JZi8lt0g4",
    "name": "Facebook",
    "type": "FACEBOOK"
  },
  "context": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko)
        Chrome/47.0.2526.106 Safari/537.36",
    "ipAddress": "127.0.0.1"
  },
  "_links": {
    "next": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/finish",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "cancel": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvkokI9JsOxqsjz0g3/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Finish Identity Provider Transaction

POST /api/v1/idps/tx/${transactionId}/finish

Finishes an IdP Transaction

No actions are completed when using callout until the /finish request completes.

Request parameters

Parameter Description Datatype Required
transactionId The Transaction ID referenced by all intermediate steps in the Transaction String TRUE

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/tx/sat4h4zexs17NrXWc0h6/finish"

Response example

HTTP/1.1 200 OK

Cancel Identity Provider Transaction

POST /api/v1/idps/tx/${transactionId}/cancel

Cancels an IdP Transaction

No actions are completed when using callout if the Transaction is canceled.

Request parameters

Parameter Description Datatype Required
transactionId The Transaction ID referenced by all intermediate steps in the Transaction String TRUE

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/tx/sat4jmxahzdtLDHOm0h6/cancel"

Response example

HTTP/1.1 200 OK

Identity Provider key store operations

Add X.509 Certificate public key

POST /api/v1/idps/credentials/keys

Adds a new X.509 certificate credential to the IdP key store

Note: RSA-based certificates are supported for all IdP types. Okta currently supports EC-based certificates only for the X509 IdP type. For EC-based certificates we support only P-256, P-384, and P-521 curves.

Request parameters
Parameter Description Param Type DataType Required
x5c Base64-encoded X.509 certificate chain with DER encoding Body Array of String TRUE
Response parameters

Identity Provider Key Credential

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "x5c": [
    "MIIDnjCCAoagAwIBAgIGAVG3MN+PMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5p
     YTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEDAOBgNVBAMM
     B2V4YW1wbGUxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTUxMjE4MjIyMjMyWhcNMjUxMjE4MjIyMzMyWjCB
     jzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9r
     dGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRAwDgYDVQQDDAdleGFtcGxlMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29t
     MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtcnyvuVCrsFEKCwHDenS3Ocjed8eWDv3zLtD2K/iZfE8BMj2wpTf
     n6Ry8zCYey3mWlKdxIybnV9amrujGRnE0ab6Q16v9D6RlFQLOG6dwqoRKuZy33Uyg8PGdEudZjGbWuKCqqXEp+UKALJHV+k4
     wWeVH8g5d1n3KyR2TVajVJpCrPhLFmq1Il4G/IUnPe4MvjXqB6CpKkog1+ThWsItPRJPAM+RweFHXq7KfChXsYE7Mmfuly8s
     DQlvBmQyxZnFHVuiPfCvGHJjpvHy11YlHdOjfgqHRvZbmo30+y0X/oY/yV4YEJ00LL6eJWU4wi7ViY3HP6/VCdRjHoRdr5L/
     DwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCzzhOFkvyYLNFj2WDcq1YqD4sBy1iCia9QpRH3rjQvMKDwQDYWbi6EdOX0TQ/I
     YR7UWGj+2pXd6v0t33lYtoKocp/4lUvT3tfBnWZ5KnObi+J2uY2teUqoYkASN7F+GRPVOuMVoVgm05ss8tuMb2dLc9vsx93s
     Dt+XlMTv/2qi5VPwaDtqduKkzwW9lUfn4xIMkTiVvCpe0X2HneD2Bpuao3/U8Rk0uiPfq6TooWaoW3kjsmErhEAs9bA7xuqo
     1KKY9CdHcFhkSsMhoeaZylZHtzbnoipUlQKSLMdJQiiYZQ0bYL83/Ta9fulr1EERICMFt3GUmtYaZZKHpWSfdJp9"
  ]
}' "https://${yourOktaDomain}/api/v1/idps/credentials/keys"
Response example
{
  "kid": "your-key-id",
  "created": "2016-01-03T18:15:47.000Z",
  "lastUpdated": "2016-01-03T18:15:47.000Z",
  "e": "65537",
  "n": "101438407598598116085679865987760095721749307901605456708912786847324207000576780508113360584
        555007890315805735307890113536927352312915634368993759211767770602174860126854831344273970871
        509573365292777620005537635317282520456901584213746937262823585533063042033441296629204165064
        680610660631365266976782082747",
  "kty": "RSA",
  "use": "sig",
  "x5c": [
    "MIIDnjCCAoagAwIBAgIGAVG3MN+PMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pY
     TEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEDAOBgNVBAMMB2
     V4YW1wbGUxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTUxMjE4MjIyMjMyWhcNMjUxMjE4MjIyMzMyWjCBjzE
     LMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9rdGEx
     FDASBgNVBAsMC1NTT1Byb3ZpZGVyMRAwDgYDVQQDDAdleGFtcGxlMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBI
     jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtcnyvuVCrsFEKCwHDenS3Ocjed8eWDv3zLtD2K/iZfE8BMj2wpTfn6Ry8z
     CYey3mWlKdxIybnV9amrujGRnE0ab6Q16v9D6RlFQLOG6dwqoRKuZy33Uyg8PGdEudZjGbWuKCqqXEp+UKALJHV+k4wWeVH8g
     5d1n3KyR2TVajVJpCrPhLFmq1Il4G/IUnPe4MvjXqB6CpKkog1+ThWsItPRJPAM+RweFHXq7KfChXsYE7Mmfuly8sDQlvBmQy
     xZnFHVuiPfCvGHJjpvHy11YlHdOjfgqHRvZbmo30+y0X/oY/yV4YEJ00LL6eJWU4wi7ViY3HP6/VCdRjHoRdr5L/DwIDAQABM
     A0GCSqGSIb3DQEBBQUAA4IBAQCzzhOFkvyYLNFj2WDcq1YqD4sBy1iCia9QpRH3rjQvMKDwQDYWbi6EdOX0TQ/IYR7UWGj+2p
     Xd6v0t33lYtoKocp/4lUvT3tfBnWZ5KnObi+J2uY2teUqoYkASN7F+GRPVOuMVoVgm05ss8tuMb2dLc9vsx93sDt+XlMTv/2q
     i5VPwaDtqduKkzwW9lUfn4xIMkTiVvCpe0X2HneD2Bpuao3/U8Rk0uiPfq6TooWaoW3kjsmErhEAs9bA7xuqo1KKY9CdHcFhk
     SsMhoeaZylZHtzbnoipUlQKSLMdJQiiYZQ0bYL83/Ta9fulr1EERICMFt3GUmtYaZZKHpWSfdJp9"
  ],
  "x5t#S256": "wzPVobIrveR1x-PCbjsFGNV-6zn7Rm9KuOWOG4Rk6jE"
}

Get key

GET /api/v1/idps/credentials/keys/${kid}

Gets a specific IdP Key Credential by kid

Request parameters
Parameter Description Param Type DataType Required
kid Unique key of the IdP Key Credential URL String TRUE
Response parameters

Identity Provider Key Credential

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/credentials/keys/your-key-id"
Response example
{
  "kid": "your-key-id",
  "created": "2016-01-03T18:15:47.000Z",
  "lastUpdated": "2016-01-03T18:15:47.000Z",
  "e": "65537",
  "n": "101438407598598116085679865987760095721749307901605456708912786847324207000576780508113360584
        555007890315805735307890113536927352312915634368993759211767770602174860126854831344273970871
        509573365292777620005537635317282520456901584213746937262823585533063042033441296629204165064
        680610660631365266976782082747",
  "kty": "RSA",
  "use": "sig",
  "x5c": [
    "MIIDnjCCAoagAwIBAgIGAVG3MN+PMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pY
     TEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEDAOBgNVBAMMB2
     V4YW1wbGUxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTUxMjE4MjIyMjMyWhcNMjUxMjE4MjIyMzMyWjCBjzE
     LMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9rdGEx
     FDASBgNVBAsMC1NTT1Byb3ZpZGVyMRAwDgYDVQQDDAdleGFtcGxlMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBI
     jANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtcnyvuVCrsFEKCwHDenS3Ocjed8eWDv3zLtD2K/iZfE8BMj2wpTfn6Ry8z
     CYey3mWlKdxIybnV9amrujGRnE0ab6Q16v9D6RlFQLOG6dwqoRKuZy33Uyg8PGdEudZjGbWuKCqqXEp+UKALJHV+k4wWeVH8g
     5d1n3KyR2TVajVJpCrPhLFmq1Il4G/IUnPe4MvjXqB6CpKkog1+ThWsItPRJPAM+RweFHXq7KfChXsYE7Mmfuly8sDQlvBmQy
     xZnFHVuiPfCvGHJjpvHy11YlHdOjfgqHRvZbmo30+y0X/oY/yV4YEJ00LL6eJWU4wi7ViY3HP6/VCdRjHoRdr5L/DwIDAQABM
     A0GCSqGSIb3DQEBBQUAA4IBAQCzzhOFkvyYLNFj2WDcq1YqD4sBy1iCia9QpRH3rjQvMKDwQDYWbi6EdOX0TQ/IYR7UWGj+2p
     Xd6v0t33lYtoKocp/4lUvT3tfBnWZ5KnObi+J2uY2teUqoYkASN7F+GRPVOuMVoVgm05ss8tuMb2dLc9vsx93sDt+XlMTv/2q
     i5VPwaDtqduKkzwW9lUfn4xIMkTiVvCpe0X2HneD2Bpuao3/U8Rk0uiPfq6TooWaoW3kjsmErhEAs9bA7xuqo1KKY9CdHcFhk
     SsMhoeaZylZHtzbnoipUlQKSLMdJQiiYZQ0bYL83/Ta9fulr1EERICMFt3GUmtYaZZKHpWSfdJp9"
  ],
  "x5t#S256": "wzPVobIrveR1x-PCbjsFGNV-6zn7Rm9KuOWOG4Rk6jE"
}

List keys

GET /api/v1/idps/credentials/keys

Enumerates IdP Key Credentials

Request parameters
Parameter Description Param Type DataType Required Default
limit Specifies the number of key results on a page Query Number FALSE 20
after Specifies the pagination cursor for the next page of keys Query String FALSE
Response parameters

Array of Identity Provider Key Credential

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/credentials/keys"
Response example
[
  {
    "kid": "your-key-id",
    "created": "2016-01-03T18:15:47.000Z",
    "lastUpdated": "2016-01-03T18:15:47.000Z",
    "e": "65537",
    "n": "101438407598598116085679865987760095721749307901605456708912786847324207000576780508113360584
          555007890315805735307890113536927352312915634368993759211767770602174860126854831344273970871
          509573365292777620005537635317282520456901584213746937262823585533063042033441296629204165064
          680610660631365266976782082747",
    "kty": "RSA",
    "use": "sig",
    "x5c": [
      "MIIDnjCCAoagAwIBAgIGAVG3MN+PMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5p
       YTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEDAOBgNVBAMM
       B2V4YW1wbGUxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTUxMjE4MjIyMjMyWhcNMjUxMjE4MjIyMzMyWjCB
       jzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9r
       dGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRAwDgYDVQQDDAdleGFtcGxlMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29t
       MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtcnyvuVCrsFEKCwHDenS3Ocjed8eWDv3zLtD2K/iZfE8BMj2wpTf
       n6Ry8zCYey3mWlKdxIybnV9amrujGRnE0ab6Q16v9D6RlFQLOG6dwqoRKuZy33Uyg8PGdEudZjGbWuKCqqXEp+UKALJHV+k4
       wWeVH8g5d1n3KyR2TVajVJpCrPhLFmq1Il4G/IUnPe4MvjXqB6CpKkog1+ThWsItPRJPAM+RweFHXq7KfChXsYE7Mmfuly8s
       DQlvBmQyxZnFHVuiPfCvGHJjpvHy11YlHdOjfgqHRvZbmo30+y0X/oY/yV4YEJ00LL6eJWU4wi7ViY3HP6/VCdRjHoRdr5L/
       DwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCzzhOFkvyYLNFj2WDcq1YqD4sBy1iCia9QpRH3rjQvMKDwQDYWbi6EdOX0TQ/I
       YR7UWGj+2pXd6v0t33lYtoKocp/4lUvT3tfBnWZ5KnObi+J2uY2teUqoYkASN7F+GRPVOuMVoVgm05ss8tuMb2dLc9vsx93s
       Dt+XlMTv/2qi5VPwaDtqduKkzwW9lUfn4xIMkTiVvCpe0X2HneD2Bpuao3/U8Rk0uiPfq6TooWaoW3kjsmErhEAs9bA7xuqo
       1KKY9CdHcFhkSsMhoeaZylZHtzbnoipUlQKSLMdJQiiYZQ0bYL83/Ta9fulr1EERICMFt3GUmtYaZZKHpWSfdJp9"
    ],
    "x5t#S256": "wzPVobIrveR1x-PCbjsFGNV-6zn7Rm9KuOWOG4Rk6jE"
  },
  {
    "kty": "EC",
    "created": "2020-04-24T20:51:20.000Z",
    "lastUpdated": "2020-04-24T20:51:20.000Z",
    "expiresAt": "2040-03-01T20:22:29.000Z",
    "alg": "EC",
    "x5c": [
        "MIICqDCCAgqgAwIBAgIJAOkmCa/S8dHiMAoGCCqGSM49BAMCMG0xCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMRAwDgYDVQQKDAdKYW5reUNvMR8wHQYDVQQDDBZUZXN0IElkZW50aXR5IFByb3ZpZGVyMB4XDTIwMDMwNjIwMjIyOVoXDTQwMDMwMTIwMjIyOVowbTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEDAOBgNVBAoMB0phbmt5Q28xHzAdBgNVBAMMFlRlc3QgSWRlbnRpdHkgUHJvdmlkZXIwgZswEAYHKoZIzj0CAQYFK4EEACMDgYYABABW/lGHl17mKDtCD4D7gcMYYOWgyWTGno8MTefDOABA8PddessTsbfrguF49Gli6lCzrZaAKhhvgINc3R6t/dYleAE3lY6LAocOoLe9xDkeggXNcSuP5fDc1x5R9GHTXl44vLoJOLSLsMbOXVMXIXoqbPDzTSYUy24aFdv4W4LZxW6ak6NQME4wHQYDVR0OBBYEFChTXNWvs4z1qjRVemPDD/hqlDQ4MB8GA1UdIwQYMBaAFChTXNWvs4z1qjRVemPDD/hqlDQ4MAwGA1UdEwQFMAMBAf8wCgYIKoZIzj0EAwIDgYsAMIGHAkIBuDhHMNLbBIsorbKtjxJzHJ2ItCSD2wAwqYv/6JBtA2ulKN5gRTSqdNCnqFsZ1/nYY7FFVXHEuQ2N3pPq7Ri8h84CQSgCq1UQyd0lFtb7+57JbiGb6LVaRqRm7vwx8zLRA+tVjIM1DlQ2Gbxkj3nlkzmM93j9wchiqGdQidyKnF6EBnfd"
    ],
    "x": "Vv5Rh5de5ig7Qg-A-4HDGGDloMlkxp6PDE3nwzgAQPD3XXrLE7G364LhePRpYupQs62WgCoYb4CDXN0erf3WJXg",
    "y": "ATeVjosChw6gt73EOR6CBc1xK4_l8NzXHlH0YdNeXji8ugk4tIuwxs5dUxcheips8PNNJhTLbhoV2_hbgtnFbpqT",
    "crv": "P-521",
    "kid": "your-kid",
    "use": "sig",
    "x5t#S256": "TUx-AIwypm2pZURHNqafk7ZDxqQP_ypzIyUwDDnPOlw"
  }
]

Update key

PUT /api/v1/idps/credentials/keys/${kid}

Request parameters
Parameter Description Param Type DataType Required
kid Unique key of the IdP Key Credential URL String TRUE
Response parameters

Identity Provider Key Credential

Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d ' {
  "x5c": [
"MIIDsjCCApqgAwIBAgIGAX3eWotJMA0GCSqGSIb3DQEBCwUAMIGZMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxGjAYBgNVBAMMEWNsYXNzaWMtbG9jYWwtYXBwMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMB4XDTIxMTIyMTE4NTU1NVoXDTIzMTIyMTE4NTY1NVowgZkxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYDVQQKDARPa3RhMRQwEgYDVQQLDAtTU09Qcm92aWRlcjEaMBgGA1UEAwwRY2xhc3NpYy1sb2NhbC1hcHAxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCHwvgfiH3XjrFo5HTzOVPTQtWAoZRtpuOJLf1wuFWdYuZLUvTtayx4jB73Ex0hs8zrN4ggQEItg+i+aNejew+tV6sg6HhRXJHoIrDbCat2FiOdk7WATtJc1+u9zVsJ4ML38U3k+fMKMkWvIHr5rawOkwyXkrmGXFFgEP208jfRYQZIcI9iw+pgpRSOoYbQMbavMrLoCrz+vOIN6SY+YYgqhf9HHuKxtriUvPnWJBgVRbQAHWTsS6yqXNo0ASabPIzHUwnHMboH2qllEZngLS8uThyS9uL318X1c0M470pOTLjNqAS+IE9ArKDqqXezOt7HYRqoUiFJjOAWDtUMtba9AgMBAAEwDQYJKoZIhvcNAQELBQADggEBAEV7IFFiX4le2i7waixDiFsFw6hKM9V0LVZbTMpWQ9CheZDZWBWZt3wCyk84wX3DbM0MIG4QhykFbqgFlWFgazgUq0rYddtSs6rne/MYt7Zbs5t6wV6m5d0VbP/7K0y1vDQUVQ2SdVLEnjWhPVU/T03mmk2JhpBLGuhHoOUDGijHRISvQd29KrtABBaWm18otOa+y+mxfXmXFNqPrG0S1TNJdelLpMztpP5S9vDrXgcWPG1w18H6lUzm84DrwBfM8q/ExxmT+YGGfAlMSaxj2HKzHheTRKbq6FBSIvf15zUy2X2suOR38zTNx7kehIZxZIY6a0PKOG+EVm04ymtYdL4="
    ],
    "x5t#S256": "bvKKSmBA8TXFXyrdhdt0GDpSNB0N8rpz74cS84shmSk",
    "e": "AQAB",
    "n": "h8L4H4h9146xaOR08zlT00LVgKGUbabjiS39cLhVnWLmS1L07WsseIwe9xMdIbPM6zeIIEBCLYPovmjXo3sPrVerIOh4UVyR6CKw2wmrdhYjnZO1gE7SXNfrvc1bCeDC9_FN5PnzCjJFryB6-a2sDpMMl5K5hlxRYBD9tPI30WEGSHCPYsPqYKUUjqGG0DG2rzKy6Aq8_rziDekmPmGIKoX_Rx7isba4lLz51iQYFUW0AB1k7EusqlzaNAEmmzyMx1MJxzG6B9qpZRGZ4C0vLk4ckvbi99fF9XNDOO9KTky4zagEviBPQKyg6ql3szrex2EaqFIhSYzgFg7VDLW2vQ"
    }' "https://${yourOktaDomain}/api/v1/idps/credentials/keys/your-key-id"
Response example
{
  "kty": "RSA",
  "created": "2022-07-12T16:11:13.000Z",
  "lastUpdated": "2022-07-12T16:17:33.000Z",
  "expiresAt": "2023-12-21T18:56:55.000Z",
  "alg": "RSA",
  "kid": "a125a828-d077-422c-8438-7c78204c1a0a",
  "use": "sig",
  "x5c": [
"MIIDsjCCApqgAwIBAgIGAX3eWotJMA0GCSqGSIb3DQEBCwUAMIGZMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxGjAYBgNVBAMMEWNsYXNzaWMtbG9jYWwtYXBwMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMB4XDTIxMTIyMTE4NTU1NVoXDTIzMTIyMTE4NTY1NVowgZkxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYDVQQKDARPa3RhMRQwEgYDVQQLDAtTU09Qcm92aWRlcjEaMBgGA1UEAwwRY2xhc3NpYy1sb2NhbC1hcHAxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCHwvgfiH3XjrFo5HTzOVPTQtWAoZRtpuOJLf1wuFWdYuZLUvTtayx4jB73Ex0hs8zrN4ggQEItg+i+aNejew+tV6sg6HhRXJHoIrDbCat2FiOdk7WATtJc1+u9zVsJ4ML38U3k+fMKMkWvIHr5rawOkwyXkrmGXFFgEP208jfRYQZIcI9iw+pgpRSOoYbQMbavMrLoCrz+vOIN6SY+YYgqhf9HHuKxtriUvPnWJBgVRbQAHWTsS6yqXNo0ASabPIzHUwnHMboH2qllEZngLS8uThyS9uL318X1c0M470pOTLjNqAS+IE9ArKDqqXezOt7HYRqoUiFJjOAWDtUMtba9AgMBAAEwDQYJKoZIhvcNAQELBQADggEBAEV7IFFiX4le2i7waixDiFsFw6hKM9V0LVZbTMpWQ9CheZDZWBWZt3wCyk84wX3DbM0MIG4QhykFbqgFlWFgazgUq0rYddtSs6rne/MYt7Zbs5t6wV6m5d0VbP/7K0y1vDQUVQ2SdVLEnjWhPVU/T03mmk2JhpBLGuhHoOUDGijHRISvQd29KrtABBaWm18otOa+y+mxfXmXFNqPrG0S1TNJdelLpMztpP5S9vDrXgcWPG1w18H6lUzm84DrwBfM8q/ExxmT+YGGfAlMSaxj2HKzHheTRKbq6FBSIvf15zUy2X2suOR38zTNx7kehIZxZIY6a0PKOG+EVm04ymtYdL4="
  ],
  "x5t#S256": "bvKKSmBA8TXFXyrdhdt0GDpSNB0N8rpz74cS84shmSk",
  "e": "AQAB",
  "n": "h8L4H4h9146xaOR08zlT00LVgKGUbabjiS39cLhVnWLmS1L07WsseIwe9xMdIbPM6zeIIEBCLYPovmjXo3sPrVerIOh4UVyR6CKw2wmrdhYjnZO1gE7SXNfrvc1bCeDC9_FN5PnzCjJFryB6-a2sDpMMl5K5hlxRYBD9tPI30WEGSHCPYsPqYKUUjqGG0DG2rzKy6Aq8_rziDekmPmGIKoX_Rx7isba4lLz51iQYFUW0AB1k7EusqlzaNAEmmzyMx1MJxzG6B9qpZRGZ4C0vLk4ckvbi99fF9XNDOO9KTky4zagEviBPQKyg6ql3szrex2EaqFIhSYzgFg7VDLW2vQ"
}

Delete key

DELETE /api/v1/idps/credentials/keys/${kid}

Deletes a specific IdP Key Credential by kid if it isn't currently being used by an active or inactive IdP

Request parameters
Parameter Description Param Type DataType Required
kid Unique key of the IdP Key Credential URL String TRUE
Response parameters

There are no response parameters.

Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/credentials/keys/74bb2164-e0c8-4457-862b-7c29ba6cd2c9"
Response example
HTTP/1.1 204 No Content

Identity Provider signing key store operations

Note: EA feature constraint: Okta currently uses the same key for both request signing and decrypting SAML assertions that the IdP encrypts. Changing your signing key also changes your decryption key.

Generate new IdP signing Key Credential

POST /api/v1/idps/${idpId}/credentials/keys/generate

Generates a new X.509 certificate for an IdP signing Key Credential to be used for signing assertions sent to the IdP

Note: To update an IdP with the newly generated Key Credential, update your IdP using the returned key's kid in the signing credential.

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
validityYears expiry of the IdP Key Credential Query Number TRUE
Response parameters

Returns the generated IdP Key Credential

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/keys/generate?validityYears=2"
Response example
{
  "created": "2015-12-10T18:56:23.000Z",
  "expiresAt": "2017-12-10T18:56:22.000Z",
  "x5c": [
    "MIIDqDCCApCgAwIBAgIGAVGNQFX5MA0GCSqGSIb3DQEBBQUAMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTAeFw0xNTEyMTAxODU1MjJaFw0xNzEyMTAxODU2MjJaMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJJjrcnI6cXBiXNq9YDgfYrQe2O5qEHG4MXP8Ue0sMeefFkFEHYHnHUeZCq6WTAGqR+1LFgOl+Eq9We5V+qNlGIfkFkQ3iHGBrIALKqLCd0Et76HicDiegz7j9DtN+lo0hG/gfcw5783L5g5xeQ7zVmCQMkFwoUA0uA3bsfUSrmfORHJL+EMNQT8XIXD8NkG4g6u7ylHVRTLgXbe+W/p04m3EP6l41xl+MhIpBaPxDsyUvcKCNwkZN3aZIin1O9Y4YJuDHxrM64/VtLLp0sC05iawAmfsLunF7rdJAkWUpPn+xkviyNQ3UpvwAYuDr+jKLUdh2reRnm1PezxMIXzBVMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEARnFIjyitrCGbleFr3KeAwdOyeHiRmgeKupX5ZopgXtcseJoToUIinX5DVw2fVZPahqs0Q7/a0wcVnTRpw6946qZCwKd/PvZ1feVuVEA5Ui3+XvHuSH5xLp7NvYG1snNEvlbN3+NDUMlWj2NEbihowUBt9+UxTpQO3+N08q3aZk3hOZ+tHt+1Te7KEEL/4CM28GZ9MY7fSrS7MAgp1+ZXtn+kRlMrXnQ49qBda37brwDRqmSY9PwNMbev3r+9ZHwxr9W5wXW4Ev4C4xngA7RkVoyDbItSUho0I0M0u/LHuppclnXrw97xyO5Z883eIBvPVjfRcxsJxXJ8jx70ATDskw=="
  ],
  "kid": "akm5hvbbevE341ovl0h7",
  "kty": "RSA",
  "use": "sig",
  "x5t#S256": "5GOpy9CQVtfvBmu2T8BHvpKE4OGtC3BuS046t7p9pps"
}

Note: If validityYears is out of range (2 through 10 years), you receive an error response.

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: generateKey",
  "errorLink": "E0000001",
  "errorId": "oaeMHrsk2WLTACvPU5T7yQ4yw",
  "errorCauses": [
    {
      "errorSummary": "Validity years out of range. It should be 2 - 10 years"
    }
  ]
}

List signing Key Credentials for IdP

GET /api/v1/idps/${idpId}/credentials/keys

Enumerates signing Key Credentials for an IdP

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
Response parameters

Array of the IdP Key Credential

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/keys"
Response example
[
  {
    "created": "2015-12-10T18:56:23.000Z",
    "expiresAt": "2017-12-10T18:56:22.000Z",
    "x5c": [
      "MIIDqDCCApCgAwIBAgIGAVGNQFX5MA0GCSqGSIb3DQEBBQUAMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTAeFw0xNTEyMTAxODU1MjJaFw0xNzEyMTAxODU2MjJaMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJJjrcnI6cXBiXNq9YDgfYrQe2O5qEHG4MXP8Ue0sMeefFkFEHYHnHUeZCq6WTAGqR+1LFgOl+Eq9We5V+qNlGIfkFkQ3iHGBrIALKqLCd0Et76HicDiegz7j9DtN+lo0hG/gfcw5783L5g5xeQ7zVmCQMkFwoUA0uA3bsfUSrmfORHJL+EMNQT8XIXD8NkG4g6u7ylHVRTLgXbe+W/p04m3EP6l41xl+MhIpBaPxDsyUvcKCNwkZN3aZIin1O9Y4YJuDHxrM64/VtLLp0sC05iawAmfsLunF7rdJAkWUpPn+xkviyNQ3UpvwAYuDr+jKLUdh2reRnm1PezxMIXzBVMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEARnFIjyitrCGbleFr3KeAwdOyeHiRmgeKupX5ZopgXtcseJoToUIinX5DVw2fVZPahqs0Q7/a0wcVnTRpw6946qZCwKd/PvZ1feVuVEA5Ui3+XvHuSH5xLp7NvYG1snNEvlbN3+NDUMlWj2NEbihowUBt9+UxTpQO3+N08q3aZk3hOZ+tHt+1Te7KEEL/4CM28GZ9MY7fSrS7MAgp1+ZXtn+kRlMrXnQ49qBda37brwDRqmSY9PwNMbev3r+9ZHwxr9W5wXW4Ev4C4xngA7RkVoyDbItSUho0I0M0u/LHuppclnXrw97xyO5Z883eIBvPVjfRcxsJxXJ8jx70ATDskw=="
    ],
    "kid": "akm5hvbbevE341ovl0h7",
    "kty": "RSA",
    "use": "sig",
    "x5t#S256": "5GOpy9CQVtfvBmu2T8BHvpKE4OGtC3BuS046t7p9pps"
  },
  {
    "created": "2015-12-10T18:55:35.000Z",
    "expiresAt": "2045-01-23T02:15:23.000Z",
    "x5c": [
      "MIIDqDCCApCgAwIBAgIGAUsUkouzMA0GCSqGSIb3DQEBBQUAMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTAeFw0xNTAxMjMwMjE0MjNaFw00NTAxMjMwMjE1MjNaMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKhmkmKsu3FYeBiJg44aN6Ah3g9gof1cytXJVMnblDUWpLfe/FMUQCssh8Y8NCYRri5jni4efBgk6B3SkC7ymqsOXILIEHSwUYWnAaqDOTxO101mHzryowu1+0PldRNoyTthahpprvAPYlTin9zrDTqFT+WY/zwoaN8H+CfixlW1nM85qF18zYYekkW50MSoHPcfJKe2ywIhPXTYTSBEPcHh8dQEjBrZn7A4qOoDnfOXll8OL7j2O6EVyTtHA0tLJHVLpwI4gSPsXFwEnHltjN57odwYe9yds0BbM/YG9i+am1+3cmZ6Uyd16mLGclrr05o9BHcEZ4ZctV2hr6whbRsCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEAnNlF27gRmhGTQ+GRAvbvYToFRgsIbBAPvRqB2LmEIiQ6UJd602w6uP1sv/zEzBYg4SnMLuVyWgOJ6d71dCvXdIO9mgAq6BaEPjlo0WhGyt+zGrpkMnIX5EwRa64kHydcPRHNA607wVYA96sJdyNJEMzBvjY9fJnfevzzDCN3NWpMS2T6rk6HP5IziI1VuFWY2OUC1kbCqLj1dUgp8koe3ftLL55ZpkAocnVMnrzBveNjgAOAiKTMcyS0bhESph9aVWvuHVZSfTnUjnTPb/4jA2YlB3ED+qaU3aqHwft1KXwZskNXBKXy7lyC+CMoeB3/ncFhSg/UllBooPPS3wYlNA=="
    ],
    "kid": "akm5hvbn1vojA9Fsa0h7",
    "kty": "RSA",
    "use": "sig",
    "x5t#S256": "7CCyXWwKzH4P6PoBP91B1S_iIZVzuGffVnUXu-BTYQQ"
  }
]

Get signing Key Credential for IdP

GET /api/v1/idps/${idpId}/credentials/keys/${kid}

Gets a specific IdP Key Credential by kid

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
kid unique key of the IdP Key Credential URL String TRUE
Response parameters

IdP Key Credential

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/keys/akm5hvbbevE341ovl0h7"
Response example
{
  "created": "2015-12-10T18:56:23.000Z",
  "expiresAt": "2017-12-10T18:56:22.000Z",
  "x5c": [
    "MIIDqDCCApCgAwIBAgIGAVGNQFX5MA0GCSqGSIb3DQEBBQUAMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTAeFw0xNTEyMTAxODU1MjJaFw0xNzEyMTAxODU2MjJaMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJJjrcnI6cXBiXNq9YDgfYrQe2O5qEHG4MXP8Ue0sMeefFkFEHYHnHUeZCq6WTAGqR+1LFgOl+Eq9We5V+qNlGIfkFkQ3iHGBrIALKqLCd0Et76HicDiegz7j9DtN+lo0hG/gfcw5783L5g5xeQ7zVmCQMkFwoUA0uA3bsfUSrmfORHJL+EMNQT8XIXD8NkG4g6u7ylHVRTLgXbe+W/p04m3EP6l41xl+MhIpBaPxDsyUvcKCNwkZN3aZIin1O9Y4YJuDHxrM64/VtLLp0sC05iawAmfsLunF7rdJAkWUpPn+xkviyNQ3UpvwAYuDr+jKLUdh2reRnm1PezxMIXzBVMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEARnFIjyitrCGbleFr3KeAwdOyeHiRmgeKupX5ZopgXtcseJoToUIinX5DVw2fVZPahqs0Q7/a0wcVnTRpw6946qZCwKd/PvZ1feVuVEA5Ui3+XvHuSH5xLp7NvYG1snNEvlbN3+NDUMlWj2NEbihowUBt9+UxTpQO3+N08q3aZk3hOZ+tHt+1Te7KEEL/4CM28GZ9MY7fSrS7MAgp1+ZXtn+kRlMrXnQ49qBda37brwDRqmSY9PwNMbev3r+9ZHwxr9W5wXW4Ev4C4xngA7RkVoyDbItSUho0I0M0u/LHuppclnXrw97xyO5Z883eIBvPVjfRcxsJxXJ8jx70ATDskw=="
  ],
  "kid": "akm5hvbbevE341ovl0h7",
  "kty": "RSA",
  "use": "sig",
  "x5t#S256": "5GOpy9CQVtfvBmu2T8BHvpKE4OGtC3BuS046t7p9pps"
}

Clone signing Key Credential for IdP

POST /api/v1/idps/${idpId}/credentials/keys/${kid}/clone?targetIdpId=${targetIdpId}

Clones an X.509 certificate for an IdP signing Key Credential from a source IdP to target IdP

Caution: Sharing certificates isn't a recommended security practice.

Request parameters
Parameter Description Param Type DataType Required
idpId id of the source IdP URL String TRUE
kid Unique key of IdP Key Credential URL String TRUE
targetIdPId id of the target IdP Query String TRUE
Response parameters

Returns the cloned IdP Key Credential

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/keys/SIMcCQNY3uwXoW3y0vf6VxiBb5n9pf8L2fK8d-FIbm4/clone?targetIdpId=0oal21k0DVN7DhS3R0g3"
Response example
{
  "created": "2015-12-10T18:56:23.000Z",
  "expiresAt": "2017-12-10T18:56:22.000Z",
  "x5c": [
    "MIIDqDCCApCgAwIBAgIGAVGNQFX5MA0GCSqGSIb3DQEBBQUAMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTAeFw0xNTEyMTAxODU1MjJaFw0xNzEyMTAxODU2MjJaMIGUMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxFTATBgNVBAMMDGJhbGFjb21wdGVzdDEcMBoGCSqGSIb3DQEJARYNaW5mb0Bva3RhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJJjrcnI6cXBiXNq9YDgfYrQe2O5qEHG4MXP8Ue0sMeefFkFEHYHnHUeZCq6WTAGqR+1LFgOl+Eq9We5V+qNlGIfkFkQ3iHGBrIALKqLCd0Et76HicDiegz7j9DtN+lo0hG/gfcw5783L5g5xeQ7zVmCQMkFwoUA0uA3bsfUSrmfORHJL+EMNQT8XIXD8NkG4g6u7ylHVRTLgXbe+W/p04m3EP6l41xl+MhIpBaPxDsyUvcKCNwkZN3aZIin1O9Y4YJuDHxrM64/VtLLp0sC05iawAmfsLunF7rdJAkWUpPn+xkviyNQ3UpvwAYuDr+jKLUdh2reRnm1PezxMIXzBVMCAwEAATANBgkqhkiG9w0BAQUFAAOCAQEARnFIjyitrCGbleFr3KeAwdOyeHiRmgeKupX5ZopgXtcseJoToUIinX5DVw2fVZPahqs0Q7/a0wcVnTRpw6946qZCwKd/PvZ1feVuVEA5Ui3+XvHuSH5xLp7NvYG1snNEvlbN3+NDUMlWj2NEbihowUBt9+UxTpQO3+N08q3aZk3hOZ+tHt+1Te7KEEL/4CM28GZ9MY7fSrS7MAgp1+ZXtn+kRlMrXnQ49qBda37brwDRqmSY9PwNMbev3r+9ZHwxr9W5wXW4Ev4C4xngA7RkVoyDbItSUho0I0M0u/LHuppclnXrw97xyO5Z883eIBvPVjfRcxsJxXJ8jx70ATDskw=="
  ],
  "kid": "SIMcCQNY3uwXoW3y0vf6VxiBb5n9pf8L2fK8d-FIbm4",
  "kty": "RSA",
  "use": "sig",
  "x5t#S256": "5GOpy9CQVtfvBmu2T8BHvpKE4OGtC3BuS046t7p9pps"
}

Note: If the key is already present in the list of Key Credentials for the target IdP, you receive a 400 error response.

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: cloneKey",
  "errorLink": "E0000001",
  "errorId": "oaeQACJOHl1TKSGj8jA3hEpAg",
  "errorCauses": [
    {
      "errorSummary": "Key already exists in the list of key credentials for the target app."
    }
  ]
}

Generate signing CSR for IdP

POST /api/v1/idps/${idpId}/credentials/csrs

Generates a new key pair and returns a Certificate Signing Request (CSR) for it.

Note: The private key isn't listed in the Signing Key Credentials for IdP until it's published.

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
metadata Metadata for the CSR Body CSR Metadata TRUE
Response parameters

Return the CSR in PKCS#10 format if the Accept media type is application/pkcs10 (opens new window) or a CSR object if the Accept media type is application/json.

Request example

Generate a new key pair and return the CSR in PKCS#10 format:

curl -v -X POST \
-H "Accept: application/pkcs10" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "subject": {
    "countryName": "US",
    "stateOrProvinceName": "California",
    "localityName": "San Francisco",
    "organizationName": "Okta, Inc.",
    "organizationalUnitName": "Dev",
    "commonName": "SP Issuer"
  },
  "subjectAltNames": {
    "dnsNames": ["dev.okta.com"]
  }
}' "https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/"

Generate a new key pair and return the CSR in JSON:

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "subject": {
    "countryName": "US",
    "stateOrProvinceName": "California",
    "localityName": "San Francisco",
    "organizationName": "Okta, Inc.",
    "organizationalUnitName": "Dev",
    "commonName": "SP Issuer"
  },
  "subjectAltNames": {
    "dnsNames": ["dev.okta.com"]
  }
}' "https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/"
Response example

Return the CSR in DER format:

HTTP/1.1 201 Created
Location: https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50
Content-Type: application/pkcs10; filename=okta.p10
Content-Transfer-Encoding: base64

MIIC4DCCAcgCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEzARBgNVBAoMCk9rdGEsIEluYy4xDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJU1AgSXNzdWVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6m8jHVCr9/tKvvbFN59T4raoCs/78KRm4fSefHQOv1TKLXo4wTLbsqYWRWc5u0sd5orUMQgPQOyj3i6qh13mALY4BzrT057EG1BUNjGg29QgYlnOk2iX890e5BIDMQQEIKFrvOi2V8cLUkLvE2ydRn0VO1Q1frbUkYeStJYC5Api2JQsYRwa+1ZeDH1ITnIzUaugWhW2WB2lSnwZkenne5KtffxMPYVu+IhNRHoKaRA6Z51YNhMJIx17JM2hs/H4Ka3drk6kzDf7ofk/yBpb9yBWyU7CTSQhdoHidxqFprMDaT66W928t3AeOENHBuwn8c2K9WeGG+bELNyQRJVmawIDAQABoCowKAYJKoZIhvcNAQkOMRswGTAXBgNVHREEEDAOggxkZXYub2t0YS5jb20wDQYJKoZIhvcNAQELBQADggEBAA2hsVJRVM+A83X9MekjTnIbt19UNT8wX7wlE9jUKirWsxceLiZBpVGn9qfKhhVIpvdaIRSeoFYS2Kg/m1G6bCvjmZLcrQ5FcEBjZH2NKfNppGVnfC2ugtUkBtCB+UUzOhKhRKJtGugenKbP33zRWWIqnd2waF6Cy8TIuqQVPbwEDN9bCbAs7ND6CFYNguY7KYjWzQOeAR716eqpEEXuPYAS4nx/ty4ylonR8cv+gpq51rvq80A4k/36aoeM0Y6I4w64vhTfuvWW2UYFUD+/+y2FA2CSP4JfctySrf1s525v6fzTFZ3qZbB5OZQtP2b8xYWktMzywsxGKDoVDB4wkH4=

Return a CSR object:

{
  "id": "h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
  "created": "2017-03-28T01:11:10.000Z",
  "csr": "MIIC4DCCAcgCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEzARBgNVBAoMCk9rdGEsIEluYy4xDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJU1AgSXNzdWVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6m8jHVCr9/tKvvbFN59T4raoCs/78KRm4fSefHQOv1TKLXo4wTLbsqYWRWc5u0sd5orUMQgPQOyj3i6qh13mALY4BzrT057EG1BUNjGg29QgYlnOk2iX890e5BIDMQQEIKFrvOi2V8cLUkLvE2ydRn0VO1Q1frbUkYeStJYC5Api2JQsYRwa+1ZeDH1ITnIzUaugWhW2WB2lSnwZkenne5KtffxMPYVu+IhNRHoKaRA6Z51YNhMJIx17JM2hs/H4Ka3drk6kzDf7ofk/yBpb9yBWyU7CTSQhdoHidxqFprMDaT66W928t3AeOENHBuwn8c2K9WeGG+bELNyQRJVmawIDAQABoCowKAYJKoZIhvcNAQkOMRswGTAXBgNVHREEEDAOggxkZXYub2t0YS5jb20wDQYJKoZIhvcNAQELBQADggEBAA2hsVJRVM+A83X9MekjTnIbt19UNT8wX7wlE9jUKirWsxceLiZBpVGn9qfKhhVIpvdaIRSeoFYS2Kg/m1G6bCvjmZLcrQ5FcEBjZH2NKfNppGVnfC2ugtUkBtCB+UUzOhKhRKJtGugenKbP33zRWWIqnd2waF6Cy8TIuqQVPbwEDN9bCbAs7ND6CFYNguY7KYjWzQOeAR716eqpEEXuPYAS4nx/ty4ylonR8cv+gpq51rvq80A4k/36aoeM0Y6I4w64vhTfuvWW2UYFUD+/+y2FA2CSP4JfctySrf1s525v6fzTFZ3qZbB5OZQtP2b8xYWktMzywsxGKDoVDB4wkH4=",
  "kty": "RSA",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "publish": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Publish signing CSR for IdP

POST /api/v1/idps/${idpId}/credentials/csrs/${csrModelId}/lifecycle/publish

Updates the CSR with a signed X.509 certificate and adds it into the signing Key Credentials for the IdP.

Note: Publishing a certificate completes the lifecycle of the CSR, and it's no longer accessible.

Request parameters
Parameter Description Param Type DataType Required
certificate The signed X.509 certificate Body X.509 certificate in DER, PEM or CER format TRUE
csrModelId id of the CSR object URL String TRUE
idpId id of the IdP URL String TRUE

For DER and CER formatted certificates, the client can either post in binary or Base64URL-encoded. If the post is Base64URL-encoded, set the Content-Transfer-Encoding header to base64.

Response parameters

Returns the new signing Key Credential.

Request example

Publish with X.509 certificate in Base64URL-encoded DER:

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/pkix-cert" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-H "Content-Transfer-Encoding: base64" \
-d "MIIFgjCCA2qgAwIBAgICEAcwDQYJKoZIhvcNAQELBQAwXjELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYDVQQKDARPa3RhMQwwCgYDVQQLDANFbmcxDTALBgNVBAMMBFJvb3QwHhcNMTcwMzI3MjEyMDQ3WhcNMTgwNDA2MjEyMDQ3WjB4MQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzETMBEGA1UECgwKT2t0YSwgSW5jLjEQMA4GA1UECwwHSmFua3lDbzEVMBMGA1UEAwwMSWRQIElzc3VlciA3MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmkC6yAJVvFwUlmM9gKjb2d+YK5qHFt+mXSsbjWKKs4EfNm+BoQeeovBZtSACyaqLc8IYFTPEURFcbDQ9DkAL04uUIRD2gaHYY7uK0jsluEaXGq2RAIsmzAwNTzkiDw4q9pDL/q7n0f/SDt1TsMaMQayB6bU5jWsmqcWJ8MCRJ1aJMjZ16un5UVx51IIeCbe4QRDxEXGAvYNczsBoZxspDt28esSpq5W0dBFxcyGVudyl54Er3FzAguhgfMVjH+bUec9j2Tl40qDTktrYgYfxz9pfjm01Hl4WYP1YQxeETpSL7cQ5Ihz4jGDtHUEOcZ4GfJrPzrGpUrak8Qp5xcwCqQIDAQABo4IBLjCCASowCQYDVR0TBAIwADARBglghkgBhvhCAQEEBAMCBkAwMwYJYIZIAYb4QgENBCYWJE9wZW5TU0wgR2VuZXJhdGVkIFNlcnZlciBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQUVqJukDmyENw/2pTApbxc/HRKbngwgZAGA1UdIwSBiDCBhYAUFx245ZZXqWTTbARfMlFWN77L9EahYqRgMF4xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEMMAoGA1UECwwDRW5nMQ0wCwYDVQQDDARSb290ggkAlIfpwZjO5o8wDgYDVR0PAQH/BAQDAgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4ICAQCcoBSRtY+9cJY00hLvq6AloYZcdn/kUQupfmyz4n3lKE3wV2FB0swKnK0QDi8iNuQJFdag/19vDHC4/LhoSuv1Q+KXM61pPZVRXXPyC1+e7Y6hj93tEI5HcqLPcDRH1AIG2l8tE7LBn+MQB5Vh6oxjG2IdoWxg6abMfISU+MauPWql4vMDUWo9iNShAo44Z5fd+nuz+hlAinU9Xn9Jf2QsfKvcbMRq7iuqgkabgdmObmWb9KK0Vm7TDkxCH0pB0onPr6epVUP8Obg/pT1Oj/1hOLbfR8CHHWdAWzUBGGvp2TIy2A8LUaEoFnwkxZfdL7Bnd0RH/ClBtAjzLOxmUo7NbZmEnYCcD5pZz7BdZI0db/eBXFqfOlA88rEe+9Sv+NndIq0/WNIIsJi2RgjJnxsxvB5MjhhzmItpFIUl5yqoO3C9jcCp6HDBJxtCGbvAr5ALPn5RCJeBIr67WpAiTd7L3Ebu9SQZlXnoHX8kP04EA6ylR3W0EFbh7KUtq8M2H2vo0wjMj7ysl/3tT7cEZ97s1ygO5iJx3GfMDyrDhtLXSBJ20uSxTJeptRw8SDiwTqunIh1WyKlcQz1WGauSbW4eXdj/r9KYMJ3qMMkdP/9THQUtTcOYx51r8RV9pdzqF2HPnZZNziBa+wXJZHEWp70NyoakNthgYwtypqiDHs2f3Q==" \
"https://${yourOktaDomain}/api/v1/idps/0oa1ysid1U3iyFqLu0g4/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish"

Publish with X.509 certificate in PEM format:

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/x-pem-file" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
--data-binary @certificate.pem \
"https://${yourOktaDomain}/api/v1/idps/0oa1ysid1U3iyFqLu0g4/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish"

Publish with X.509 certificate in binary CER format:

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/x-x509-ca-cert" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
--data-binary @certificate.cer \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/0oa1ysid1U3iyFqLu0g4/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish"
Response example
{
    "created": "2017-03-27T21:19:57.000Z",
    "lastUpdated": "2017-03-27T21:19:57.000Z",
    "expiresAt": "2018-04-06T21:20:47.000Z",
    "x5c": [
      "MIIFgjCCA2qgAwIBAgICEAcwDQYJKoZIhvcNAQELBQAwXjELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ0wCwYDVQQKDARPa3RhMQwwCgYDVQQLDANFbmcxDTALBgNVBAMMBFJvb3QwHhcNMTcwMzI3MjEyMDQ3WhcNMTgwNDA2MjEyMDQ3WjB4MQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzETMBEGA1UECgwKT2t0YSwgSW5jLjEQMA4GA1UECwwHSmFua3lDbzEVMBMGA1UEAwwMSWRQIElzc3VlciA3MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmkC6yAJVvFwUlmM9gKjb2d+YK5qHFt+mXSsbjWKKs4EfNm+BoQeeovBZtSACyaqLc8IYFTPEURFcbDQ9DkAL04uUIRD2gaHYY7uK0jsluEaXGq2RAIsmzAwNTzkiDw4q9pDL/q7n0f/SDt1TsMaMQayB6bU5jWsmqcWJ8MCRJ1aJMjZ16un5UVx51IIeCbe4QRDxEXGAvYNczsBoZxspDt28esSpq5W0dBFxcyGVudyl54Er3FzAguhgfMVjH+bUec9j2Tl40qDTktrYgYfxz9pfjm01Hl4WYP1YQxeETpSL7cQ5Ihz4jGDtHUEOcZ4GfJrPzrGpUrak8Qp5xcwCqQIDAQABo4IBLjCCASowCQYDVR0TBAIwADARBglghkgBhvhCAQEEBAMCBkAwMwYJYIZIAYb4QgENBCYWJE9wZW5TU0wgR2VuZXJhdGVkIFNlcnZlciBDZXJ0aWZpY2F0ZTAdBgNVHQ4EFgQUVqJukDmyENw/2pTApbxc/HRKbngwgZAGA1UdIwSBiDCBhYAUFx245ZZXqWTTbARfMlFWN77L9EahYqRgMF4xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEMMAoGA1UECwwDRW5nMQ0wCwYDVQQDDARSb290ggkAlIfpwZjO5o8wDgYDVR0PAQH/BAQDAgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4ICAQCcoBSRtY+9cJY00hLvq6AloYZcdn/kUQupfmyz4n3lKE3wV2FB0swKnK0QDi8iNuQJFdag/19vDHC4/LhoSuv1Q+KXM61pPZVRXXPyC1+e7Y6hj93tEI5HcqLPcDRH1AIG2l8tE7LBn+MQB5Vh6oxjG2IdoWxg6abMfISU+MauPWql4vMDUWo9iNShAo44Z5fd+nuz+hlAinU9Xn9Jf2QsfKvcbMRq7iuqgkabgdmObmWb9KK0Vm7TDkxCH0pB0onPr6epVUP8Obg/pT1Oj/1hOLbfR8CHHWdAWzUBGGvp2TIy2A8LUaEoFnwkxZfdL7Bnd0RH/ClBtAjzLOxmUo7NbZmEnYCcD5pZz7BdZI0db/eBXFqfOlA88rEe+9Sv+NndIq0/WNIIsJi2RgjJnxsxvB5MjhhzmItpFIUl5yqoO3C9jcCp6HDBJxtCGbvAr5ALPn5RCJeBIr67WpAiTd7L3Ebu9SQZlXnoHX8kP04EA6ylR3W0EFbh7KUtq8M2H2vo0wjMj7ysl/3tT7cEZ97s1ygO5iJx3GfMDyrDhtLXSBJ20uSxTJeptRw8SDiwTqunIh1WyKlcQz1WGauSbW4eXdj/r9KYMJ3qMMkdP/9THQUtTcOYx51r8RV9pdzqF2HPnZZNziBa+wXJZHEWp70NyoakNthgYwtypqiDHs2f3Q=="
    ],
    "e": "AQAB",
    "n": "mkC6yAJVvFwUlmM9gKjb2d-YK5qHFt-mXSsbjWKKs4EfNm-BoQeeovBZtSACyaqLc8IYFTPEURFcbDQ9DkAL04uUIRD2gaHYY7uK0jsluEaXGq2RAIsmzAwNTzkiDw4q9pDL_q7n0f_SDt1TsMaMQayB6bU5jWsmqcWJ8MCRJ1aJMjZ16un5UVx51IIeCbe4QRDxEXGAvYNczsBoZxspDt28esSpq5W0dBFxcyGVudyl54Er3FzAguhgfMVjH-bUec9j2Tl40qDTktrYgYfxz9pfjm01Hl4WYP1YQxeETpSL7cQ5Ihz4jGDtHUEOcZ4GfJrPzrGpUrak8Qp5xcwCqQ",
    "kid": "ZC5C-1gEUwVxiYI8xdmYYDI3Noc4zI24fLNxBpZVR04",
    "kty": "RSA",
    "use": "sig",
    "x5t#S256": "lt0HQ-Ty_f_5icHGjUTrrNSO6dofPTRoPzOZhNSg5Kc"
  }

Note: If the validity period of the certificate is less than 90 days, a 400 error response is returned.

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: certificate",
  "errorLink": "E0000001",
  "errorId": "oaeu3Ej_tjlSXytiahRUasoSg",
  "errorCauses": [
    {
      "errorSummary": "The certificate does not match the CSR."
    }
  ]
}

Revoke signing CSR from IdP

DELETE /api/v1/idps/${idpId}/credentials/csrs/${csrModelId}

Revokes a CSR and deletes the key pair from the IdP

Request parameters
Parameter Description Param Type DataType Required
csrModelId id of CSR object URL String TRUE
idpId id of the IdP URL String TRUE
Response parameters

Empty response

Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/-_-BFwAGoUYN-DDvsSKQFdx7OXaPZqrEPpFDO1hu-rg"
Response example
HTTP/1.1 204 No Content

List signing CSRs for IdP

GET /api/v1/idps/${idpId}/credentials/csrs

Enumerates signing CSRs for an IdP

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
Response parameters

Array of CSR objects

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs"
Response example
[
  {
    "id": "h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
    "created": "2017-03-28T01:11:10.000Z",
    "csr": "MIIC4DCCAcgCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEzARBgNVBAoMCk9rdGEsIEluYy4xDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJU1AgSXNzdWVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6m8jHVCr9/tKvvbFN59T4raoCs/78KRm4fSefHQOv1TKLXo4wTLbsqYWRWc5u0sd5orUMQgPQOyj3i6qh13mALY4BzrT057EG1BUNjGg29QgYlnOk2iX890e5BIDMQQEIKFrvOi2V8cLUkLvE2ydRn0VO1Q1frbUkYeStJYC5Api2JQsYRwa+1ZeDH1ITnIzUaugWhW2WB2lSnwZkenne5KtffxMPYVu+IhNRHoKaRA6Z51YNhMJIx17JM2hs/H4Ka3drk6kzDf7ofk/yBpb9yBWyU7CTSQhdoHidxqFprMDaT66W928t3AeOENHBuwn8c2K9WeGG+bELNyQRJVmawIDAQABoCowKAYJKoZIhvcNAQkOMRswGTAXBgNVHREEEDAOggxkZXYub2t0YS5jb20wDQYJKoZIhvcNAQELBQADggEBAA2hsVJRVM+A83X9MekjTnIbt19UNT8wX7wlE9jUKirWsxceLiZBpVGn9qfKhhVIpvdaIRSeoFYS2Kg/m1G6bCvjmZLcrQ5FcEBjZH2NKfNppGVnfC2ugtUkBtCB+UUzOhKhRKJtGugenKbP33zRWWIqnd2waF6Cy8TIuqQVPbwEDN9bCbAs7ND6CFYNguY7KYjWzQOeAR716eqpEEXuPYAS4nx/ty4ylonR8cv+gpq51rvq80A4k/36aoeM0Y6I4w64vhTfuvWW2UYFUD+/+y2FA2CSP4JfctySrf1s525v6fzTFZ3qZbB5OZQtP2b8xYWktMzywsxGKDoVDB4wkH4=",
    "kty": "RSA",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
        "hints": {
          "allow": [
            "GET",
            "DELETE"
          ]
        }
      },
      "publish": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  },
  {
    "id": "-_-BFwAGoUYN-DDvsSKQFdx7OXaPZqrEPpFDO1hu-rg",
    "created": "2017-03-28T01:21:10.000Z",
    "csr": "MIIC4DCCAcgCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEzARBgNVBAoMCk9rdGEsIEluYy4xDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJU1AgSXNzdWVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6m8jHVCr9/tKvvbFN59T4raoCs/78KRm4fSefHQOv1TKLXo4wTLbsqYWRWc5u0sd5orUMQgPQOyj3i6qh13mALY4BzrT057EG1BUNjGg29QgYlnOk2iX890e5BIDMQQEIKFrvOi2V8cLUkLvE2ydRn0VO1Q1frbUkYeStJYC5Api2JQsYRwa+1ZeDH1ITnIzUaugWhW2WB2lSnwZkenne5KtffxMPYVu+IhNRHoKaRA6Z51YNhMJIx17JM2hs/H4Ka3drk6kzDf7ofk/yBpb9yBWyU7CTSQhdoHidxqFprMDaT66W928t3AeOENHBuwn8c2K9WeGG+bELNyQRJVmawIDAQABoCowKAYJKoZIhvcNAQkOMRswGTAXBgNVHREEEDAOggxkZXYub2t0YS5jb20wDQYJKoZIhvcNAQELBQADggEBAA2hsVJRVM+A83X9MekjTnIbt19UNT8wX7wlE9jUKirWsxceLiZBpVGn9qfKhhVIpvdaIRSeoFYS2Kg/m1G6bCvjmZLcrQ5FcEBjZH2NKfNppGVnfC2ugtUkBtCB+UUzOhKhRKJtGugenKbP33zRWWIqnd2waF6Cy8TIuqQVPbwEDN9bCbAs7ND6CFYNguY7KYjWzQOeAR716eqpEEXuPYAS4nx/ty4ylonR8cv+gpq51rvq80A4k/36aoeM0Y6I4w64vhTfuvWW2UYFUD+/+y2FA2CSP4JfctySrf1s525v6fzTFZ3qZbB5OZQtP2b8xYWktMzywsxGKDoVDB4wkH4=",
    "kty": "RSA",
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/-_-BFwAGoUYN-DDvsSKQFdx7OXaPZqrEPpFDO1hu-rg",
        "hints": {
          "allow": [
            "GET",
            "DELETE"
          ]
        }
      },
      "publish": {
        "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/-_-BFwAGoUYN-DDvsSKQFdx7OXaPZqrEPpFDO1hu-rg/lifecycle/publish",
        "hints": {
          "allow": [
            "POST"
          ]
        }
      }
    }
  }
]

Get signing CSR for IdP

GET /api/v1/idps/${idpId}/credentials/csrs/${csrModelId}

Gets a specific CSR object by id

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
csrModelId id of CSR object URL String TRUE
Response parameters

Returns Base64URL-encoded CSR in DER format if the Accept media type is application/pkcs10 or a CSR object if the Accept media type is application/json

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50"
Response example
{
  "id": "h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
  "created": "2017-03-28T01:11:10.000Z",
  "csr": "MIIC4DCCAcgCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEzARBgNVBAoMCk9rdGEsIEluYy4xDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJU1AgSXNzdWVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6m8jHVCr9/tKvvbFN59T4raoCs/78KRm4fSefHQOv1TKLXo4wTLbsqYWRWc5u0sd5orUMQgPQOyj3i6qh13mALY4BzrT057EG1BUNjGg29QgYlnOk2iX890e5BIDMQQEIKFrvOi2V8cLUkLvE2ydRn0VO1Q1frbUkYeStJYC5Api2JQsYRwa+1ZeDH1ITnIzUaugWhW2WB2lSnwZkenne5KtffxMPYVu+IhNRHoKaRA6Z51YNhMJIx17JM2hs/H4Ka3drk6kzDf7ofk/yBpb9yBWyU7CTSQhdoHidxqFprMDaT66W928t3AeOENHBuwn8c2K9WeGG+bELNyQRJVmawIDAQABoCowKAYJKoZIhvcNAQkOMRswGTAXBgNVHREEEDAOggxkZXYub2t0YS5jb20wDQYJKoZIhvcNAQELBQADggEBAA2hsVJRVM+A83X9MekjTnIbt19UNT8wX7wlE9jUKirWsxceLiZBpVGn9qfKhhVIpvdaIRSeoFYS2Kg/m1G6bCvjmZLcrQ5FcEBjZH2NKfNppGVnfC2ugtUkBtCB+UUzOhKhRKJtGugenKbP33zRWWIqnd2waF6Cy8TIuqQVPbwEDN9bCbAs7ND6CFYNguY7KYjWzQOeAR716eqpEEXuPYAS4nx/ty4ylonR8cv+gpq51rvq80A4k/36aoeM0Y6I4w64vhTfuvWW2UYFUD+/+y2FA2CSP4JfctySrf1s525v6fzTFZ3qZbB5OZQtP2b8xYWktMzywsxGKDoVDB4wkH4=",
  "kty": "RSA",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "publish": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Identity Provider User operations

Find Users

GET /api/v1/idps/${idpId}/users

Finds all the Users linked to an Identity Provider

Request parameters
Parameter Description Param Type DataType Required
idpId id of IdP to search URL String TRUE
q query or search term for user URL or body String FALSE
after Cursor of the query URL or body String FALSE
limit Max number of users to show URL or body String FALSE
expand Expand user data URL or body String FALSE
Response parameters

List of Users that are linked to the specified Identity Provider

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oa4lb6lbtmH355Hx0h7/users"
Response example
[
  {
      "id": "00u5cl9lo7nMjHjPr0h7",
      "externalId": "109912936038778",
      "created": "2015-11-03T19:10:11.000Z",
      "lastUpdated": "2015-11-03T19:11:49.000Z",
      "profile": {
          "firstName": "Carol",
          "middleName": "Lee",
          "lastName": "Johnson",
          "email": "carol_johnson@tfbnw.net",
          "displayName": "Carol Johnson",
          "profile": "https://www.facebook.com/app_scoped_user_id/109912936038778/"
      },
      "_links": {
        "self": {
          "href": "https://{yourOktaDomain}/api/v1/idps/0oa4lb6lbtmH355Hx0h7/users/00u5cl9lo7nMjHjPr0h7",
          "hints": {
              "allow": [
                  "GET",
                  "DELETE"
                ]
          }
        },
        "idp": {
            "href": "https://{yourOktaDomain}/api/v1/idps/0oa4lb6lbtmH355Hx0h7"
        },
        "user": {
            "href": "https://{yourOktaDomain}/api/v1/users/00u5cl9lo7nMjHjPr0h7"
        }
     }
  }
]

List IdPs associated with a User

GET /api/v1/users/${userId}/idps

Lists the IdPs associated with the User

Request parameters
Parameter Description Param Type DataType Required
userId id of a User URL String TRUE
Response parameters

Return the associated Identity Providers

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR/idps"
Response example
[{
  "id": "0oa62b57p7c8PaGpU0h7",
  "type": "FACEBOOK",
  "name": "Facebook",
  "status": "ACTIVE",
  "created": "2016-03-24T23:18:27.000Z",
  "lastUpdated": "2016-03-24T23:18:27.000Z",
  "protocol": {
    "type": "OAUTH2",
    "endpoints": {
      "authorization": {
        "url": "https://www.facebook.com/dialog/oauth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://graph.facebook.com/v2.5/oauth/access_token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "public_profile",
      "email"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.userPrincipalName"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 0
  },
  "_links": {
    "authorize": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oa62b57p7c8PaGpU0h7&
          client_id={clientId}&response_type={responseType}&response_mode={responseMode}&
          scope={scopes}&redirect_uri={redirectUri}&state={state}",
      "templated": true,
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "clientRedirectUri": {
      "href": "https://{yourOktaDomain}/oauth2/v1/authorize/callback",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "idpUser": {
        "href": "https://{yourOktaDomain}/idps/0oa62b57p7c8PaGpU0h7/users/00ub0oNGTSWTBKOLGLNR",
        "hints": {
          "allow": [
            "GET",
            "DELETE"
          ]
        }
      }
  }
}]

Note: If the user doesn't exist, you receive an error response.

{
  "errorCode": "E0000007",
  "errorSummary": "Not found: Resource not found: 00ub0oNGTSWTBKOLGLNR (User)",
  "errorLink": "E0000007",
  "errorId": "oaeYW9k9yJuSSSkhaMQdA1-Zg",
  "errorCauses": []
}

Get a linked Identity Provider User

GET /api/v1/idps/${idpId}/users/${userId}

Fetches a linked IdP User by ID

Request parameters
Parameter Description Param Type DataType Required
idpId ID of the Identity Provider URL String TRUE
userId id of a User URL String TRUE
Response parameters

Return the associated Identity Providers

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oa62bfdiumsUndnZ0h7/users/00u5t60iloOHN9pBi0h7"
Response example
{
    "id": "00u5t60iloOHN9pBi0h7",
    "externalId": "externalId",
    "created": "2017-12-19T17:30:16.000Z",
    "lastUpdated": "2017-12-19T17:30:16.000Z",
    "profile": {
        "profileUrl": null,
        "firstName": null,
        "lastName": null,
        "honorificSuffix": null,
        "displayName": null,
        "honorificPrefix": null,
        "middleName": null,
        "email": null
    },
    "_links": {
        "idp": {
            "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bfdiumsUndnZ0h7"
        },
        "self": {
            "href": "https://{yourOktaDomain}/api/v1/idps/0oa62bfdiumsUndnZ0h7/users/00u5t60iloOHN9pBi0h7",
            "hints": {
                "allow": [
                    "GET",
                    "DELETE"
                ]
            }
        },
        "user": {
            "href": "https://{yourOktaDomain}/api/v1/users/00u5t60iloOHN9pBi0h7"
        }
    }
}

Note: If the IdP doesn't exist, you receive an error response.

{
  "errorCode": "E0000007",
  "errorSummary": "Not found: Resource not found: 0oa62bfdiumsUndnZ0h8 (IdpAppInstance)",
  "errorLink": "E0000007",
  "errorId": "oaeYW9k9yJuSSSkhaMQdA1-Zg",
  "errorCauses": []
}

POST /api/v1/idps/${idpId}/users/${userId}

Links an Okta User to an existing SAML or social provider. The SAML Identity Provider must have honorPersistentNameId set to true to use this API. The Name Identifier Format of the incoming assertion must be urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

Request parameters
Parameter Description Param Type DataType Required
externalId unique IdP-specific identifier for a User Body String TRUE
idpId id of the IdP URL String TRUE
userId id of a User URL String TRUE
Response parameters

Return the associated Identity Providers

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "externalId": "121749775026145"
}' "https://${yourOktaDomain}/api/v1/idps/0oa62b57p7c8PaGpU0h7/users/00ub0oNGTSWTBKOLGLNR"
Response example
{
  "id": "00ub0oNGTSWTBKOLGLNR",
  "externalId": "121749775026145",
  "created": "2017-03-30T02:19:51.000Z",
  "lastUpdated": "2017-03-30T02:19:51.000Z",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62b57p7c8PaGpU0h7/users/00ub0oNGTSWTBKOLGLNR",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "idp": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa62b57p7c8PaGpU0h7"
    },
    "user": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ub0oNGTSWTBKOLGLNR"
    }
  }
}

Note: If either the User or the IdP doesn't exist, you receive an error response.

{
  "errorCode": "E0000007",
  "errorSummary": "Not found: Resource not found: 00ub0oNGTSWTBKOLGLNR (User)",
  "errorLink": "E0000007",
  "errorId": "oaeYW9k9yJuSSSkhaMQdA1-Zg",
  "errorCauses": []
}

DELETE /api/v1/idps/${idpId}/users/${userId}

Removes the link between the Okta User and the IdP User. The next time the User federates into Okta through this IdP, they have to re-link their account according to the account link policy configured in Okta for this IdP.

Request parameters
Parameter Description Param Type DataType Required
idpId id of IdP to activate URL String TRUE
userId id of user to delete URL String TRUE
Response parameters
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
-d '{
}' "https://${yourOktaDomain}/api/v1/idps/0oa4lb6lbtmH355Hx0h7/users/00u5cl9lo7nMjHjPr0h7"
Response example
204 - No Content

Social authentication token operation

GET /api/v1/idps/${idpId}/users/${userId}/credentials/tokens

Okta doesn't import all the User information from a social provider. If the app needs information that isn't imported, it can get the User token from this endpoint, and then make an API call to the social provider with the token to request the additional information.

Request parameters
Parameter Description Param Type DataType Required
idpId id of the IdP URL String TRUE
userId id of a User URL String TRUE
Response parameters

Return a list of the associated social authentication tokens

Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "User-Agent: Mozilla/5.0 (${systemInformation}) ${platform} (${platformDetails}) ${extensions}" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/idps/0oa62b57p7c8PaGpU0h7/users/00ub0oNGTSWTBKOLGLNR/credentials/tokens"
Response example
[{
  "id": "dsasdfe",
  "token": "JBTWGV22G4ZGKV3N",
  "tokenType" : "urn:ietf:params:oauth:token-type:access_token",
  "tokenAuthScheme": "Bearer",
  "expiresAt" : "2014-08-06T16:56:31.000Z",
  "scopes"     : [ "openid", "foo" ]
 },
 {
    "id": "dsasdsasdfe",
    "token": "JBTWGV22G4ZJBRXJ",
    "tokenType" : "urn:ietf:params:oauth:token-type:id_token",
    "tokenAuthScheme": null
}]

Identity Provider object

Example

{
  "id": "0oa1k5d68qR2954hb0g4",
  "type": "SAML2",
  "issuerMode": "ORG_URL",
  "name": "Example SAML IdP",
  "status": "ACTIVE",
  "created": "2015-03-05T20:24:09.000Z",
  "lastUpdated": "2015-12-18T05:19:40.000Z",
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "sso": {
        "url": "https://idp.example.com/saml2/sso",
        "binding": "HTTP-REDIRECT",
        "destination": "https://idp.example.com/saml2/sso"
      },
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      }
    },
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-1",
          "scope": "REQUEST"
        }
      },
      "response": {
        "signature": {
          "algorithm": "SHA-1",
          "scope": "ANY"
        }
      }
    },
    "credentials": {
      "trust": {
        "issuer": "urn:example:idp",
        "audience": "https://www.okta.com/saml2/service-provider/spgv32vOnpdyeGSaiUpL",
        "kid": "your-key-id"
      }
    }
  },
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.subjectNameId"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 120000
  },
  "_links": {
    "metadata": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa1k5d68qR2954hb0g4/metadata.xml",
      "type": "application/xml",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "acs": {
      "href": "https://{yourOktaDomain}/sso/saml2/0oa1k5d68qR2954hb0g4",
      "type": "application/xml",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "users": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa1k5d68qR2954hb0g4/users",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "activate": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa1k5d68qR2954hb0g4/lifecycle/activate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "deactivate": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa1k5d68qR2954hb0g4/lifecycle/deactivate",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Identity Provider attributes

All Identity Providers have the following properties:

Property Description DataType Nullable Unique Readonly MinLength MaxLength
_embedded Embedded resources related to the IdP JSON HAL (opens new window) TRUE FALSE TRUE
_links Discoverable resources related to the IdP JSON HAL (opens new window) TRUE FALSE TRUE
created Timestamp when the IdP was created Date FALSE FALSE TRUE
id Unique key for the IdP String FALSE TRUE TRUE
issuerMode Indicates whether Okta uses the original Okta org domain URL or a custom domain URL in the request to the social IdP ORG_URL, CUSTOM_URL, or DYNAMIC FALSE FALSE FALSE
lastUpdated Timestamp when the IdP was last updated Date FALSE FALSE TRUE
name Unique name for the IdP String FALSE TRUE FALSE 1 100
policy Policy settings for IdP type Policy object FALSE FALSE FALSE
protocol Protocol settings for IdP type Protocol object FALSE FALSE FALSE
status Status of the IdP ACTIVE or INACTIVE FALSE FALSE TRUE
type Type of IdP Identity Provider Type FALSE FALSE FALSE
properties Properties specific to the type of IdP Identity Provider Properties TRUE FALSE FALSE

Property details

  • The id, created, lastUpdated, and _links properties are available after an IdP is created.

  • issuerMode indicates which URL Okta uses in the request to the social IdP. You can set issuerMode to CUSTOM_URL only if you have a custom URL domain configured.

    • If set to ORG_URL, then in the authorize request to the social IdP, Okta uses the Okta org's original domain URL (https://${yourOktaDomain}) as the domain in the redirect_uri.

    • If set to CUSTOM_URL, then in the authorize request to the social IdP, Okta uses the custom domain URL as the domain in the redirect_uri.

    • If set to DYNAMIC, then in the authorize request to the social IdP, Okta uses the custom domain URL as the domain in the redirect_uri if the request was made from the custom domain URL. Otherwise, Okta uses the Okta org's original domain URL if the request was made from the Okta org domain.

    All new social IdPs use the DYNAMIC issuerMode by default. All existing social IdPs continue to use the issuerMode they were configured with (ORG_URL or CUSTOM_URL). You can change this value in any social IdP through the API or Admin Console.

  • The Protocol object (protocol) and Policy object (policy) are dependent on the specific type (type) of IdP used.

  • The properties in the Identity Provider Properties object are dependent on the specific type (type) of IdP used.

Identity Provider type

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.

Okta supports the following enterprise and social Identity Provider types:

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

Identity Provider Properties

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

Property Description DataType Applies to IdP type
additionalAmr The additional Assurance Methods References (AMR) values for Smart Card IdPs.
Supported values: sc (smart card), hwk (hardware-secured key), pin (personal identification number), and mfa (multifactor authentication)
Array of strings X509
ialValue The type of identity verification (opens new window) (IAL) value for the Login.gov IdP. See Add a Login.gov IdP. String LOGINGOV, LOGINGOV_SANDBOX
aalValue The authentication assurance level (opens new window) (AAL) value for the Login.gov IdP. See Add a Login.gov IdP. String LOGINGOV, LOGINGOV_SANDBOX

Protocol object

The Protocol object contains IdP-specific protocol settings for endpoints, bindings, and algorithms used to connect with the IdP and validate messages. The following are the supported Protocol objects:

SAML 2.0 Protocol

Protocol settings for the SAML 2.0 Authentication Request Protocol (opens new window):

Property Description DataType Nullable Readonly
algorithms Settings for signing and verifying SAML messages SAML 2.0 Algorithms object FALSE FALSE
credentials Federation trust credentials for verifying assertions from the IdP SAML 2.0 Credentials object FALSE FALSE
endpoints SAML 2.0 HTTP binding settings for IdP and SP (Okta) SAML 2.0 Endpoints object FALSE FALSE
relayState Relay state settings for IdP SAML 2.0 Relay State object TRUE FALSE
settings Advanced settings for the SAML 2.0 protocol SAML 2.0 Settings object TRUE FALSE
type SAML 2.0 protocol SAML2 FALSE TRUE
{
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "sso": {
        "url": "https://idp.example.com/saml2/sso",
        "binding": "HTTP-POST",
        "destination": "https://idp.example.com/saml2/sso"
      },
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      }
    },
    "relayState": {
      "format": "FROM_URL"
    },
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-1",
          "scope": "REQUEST"
        }
      },
      "response": {
        "signature": {
          "algorithm": "SHA-1",
          "scope": "ANY"
        }
      }
    },
    "credentials": {
      "trust": {
        "issuer": "urn:example:idp",
        "audience": "https://www.okta.com/saml2/service-provider/spgv32vOnpdyeGSaiUpL",
        "kid": "your-key-id"
      }
    },
    "settings": {
        "nameFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
        "honorPersistentNameId": false
    }
  }
}
SAML 2.0 endpoints object

The SAML2 protocol supports the sso and acs endpoints.

Property Description DataType Nullable Readonly
acs Okta's SPSSODescriptor endpoint where the IdP sends a <SAMLResponse> message Assertion Consumer Service (ACS) Endpoint object FALSE FALSE
sso IdP's SingleSignOnService endpoint where Okta sends an <AuthnRequest> message Single Sign-On (SSO) Endpoint object FALSE FALSE
Single Sign-On (SSO) endpoint object

The Single Sign-On (SSO) endpoint is the IdP's SingleSignOnService endpoint where Okta sends a SAML 2.0 <AuthnRequest> message:

Property Description DataType Nullable Readonly MinLength MaxLength Validation
binding HTTP binding used to send an <AuthnRequest> message to the IdP HTTP-POST or HTTP-Redirect FALSE FALSE
destination URI reference that indicates the address to which the <AuthnRequest> message is sent String TRUE FALSE 1 512
url URL of the binding-specific endpoint to send an <AuthnRequest> message to the IdP String FALSE FALSE 11 1014 RFC 3986 (opens new window)

Property details

  • The destination property is required if request signatures are specified. See SAML 2.0 Request Algorithm object.
  • The value of url is defaulted to the same value as the sso endpoint if omitted during creation of a new IdP instance.
{
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "sso": {
        "url": "https://idp.example.com/saml2/sso",
        "binding": "HTTP-POST",
        "destination": "https://idp.example.com/saml2/sso"
      }
    }
  }
}
  • The url should be the same value as the Location attribute for a published binding in the IdP's SAML Metadata IDPSSODescriptor.
<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
  <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://idp.example.com/saml2/sso"/>
  <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://idp.example.com/saml2/sso"/>
</IDPSSODescriptor>
Assertion Consumer Service (ACS) endpoint object

The ACS endpoint is Okta's SPSSODescriptor endpoint where the IdP sends a SAML 2.0 <SAMLResponse> message.

Property Description DataType Nullable Readonly Default
binding HTTP binding used to receive a <SAMLResponse> message from the IdP HTTP-POST TRUE FALSE HTTP-POST
type Determines whether to publish an instance-specific (trust) or organization (shared) ACS endpoint in the SAML metadata INSTANCE or ORG TRUE FALSE INSTANCE
{
  "protocol": {
    "type": "SAML2",
    "endpoints": {
      "acs": {
        "binding": "HTTP-POST",
        "type": "INSTANCE"
      }
    }
  }
}

Trust-specific ACS endpoint example

<md:EntityDescriptor entityID="https://sp.example.com/saml2/sso" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://{yourOktaDomain}/sso/saml2/0oamxfD9Jvaxvr0M00g3" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Tip: Note the unique IdP instance id in the ACS Location.

Organization (shared) ACS endpoint example

<md:EntityDescriptor entityID="https://sp.example.com/saml2/sso" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://{yourOktaDomain}/sso/saml2" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Note: An organization-specific ACS endpoint enables multiple trusts from an IdP to a single ACS URL that specific IdP vendors may require.

SAML 2.0 Relay State object
Property Description DataType Nullable Readonly
format The format used to generate the relayState in the SAML request. FROM_URL is used if this value is null. OPAQUE or FROM_URL TRUE FALSE
{
  "protocol": {
    "type": "SAML2",
    "relayState": {
      "format": "OPAQUE"
    }
  }
}
SAML 2.0 Algorithms object

The SAML2 protocol supports request and response algorithm and verification settings.

Property Description DataType Nullable Readonly
request Algorithm settings used to secure an <AuthnRequest> message SAML 2.0 Request Algorithm object FALSE FALSE
response Algorithm settings used to verify a <SAMLResponse> message SAML 2.0 Response Algorithm object FALSE FALSE
{
  "protocol": {
    "type": "SAML2",
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-1",
          "scope": "REQUEST"
        }
      },
      "response": {
        "signature": {
          "algorithm": "SHA-1",
          "scope": "ANY"
        }
      }
    }
  }
}
SAML 2.0 Request Algorithm object

Algorithm settings for securing <AuthnRequest> messages sent to the IdP:

Property Description DataType Nullable Readonly
signature Algorithm settings used to sign an <AuthnRequest> message SAML 2.0 Request Signature Algorithm object FALSE FALSE
{
  "protocol": {
    "type": "SAML2",
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "REQUEST"
        }
      }
    }
  }
}
SAML 2.0 request Signature Algorithm object

XML digital Signature Algorithm settings for signing <AuthnRequest> messages sent to the IdP:

Property Description DataType Nullable Readonly
algorithm The XML digital Signature Algorithm used when signing an <AuthnRequest> message SHA-1 or SHA-256 FALSE FALSE
scope Specifies whether to digitally sign <AuthnRequest> messages to the IdP REQUEST or NONE FALSE FALSE

Note: The algorithm property is ignored when you disable request signatures (scope set as NONE).

SAML 2.0 response Algorithm object

Algorithm settings for verifying <SAMLResponse> messages and <Assertion> elements from the IdP:

Property Description DataType Nullable Readonly
signature Algorithm settings for verifying <SAMLResponse> messages and <Assertion> elements from the IdP SAML 2.0 Response Signature Algorithm object FALSE FALSE
{
  "protocol": {
    "type": "SAML2",
    "algorithms": {
      "response": {
        "signature": {
          "algorithm": "SHA-256",
          "scope": "ANY"
        }
      }
    }
  }
}
SAML 2.0 response Signature Algorithm object

XML digital Signature Algorithm settings for verifying <SAMLResponse> messages and <Assertion> elements from the IdP:

Property Description DataType Nullable Readonly
algorithm The minimum XML digital Signature Algorithm allowed when verifying a <SAMLResponse> message or <Assertion> element SHA-1 or SHA-256 FALSE FALSE
scope Specifies whether to verify a <SAMLResponse> message or <Assertion> element XML digital signature RESPONSE, TOKEN, ANY FALSE FALSE
SAML 2.0 Credentials object

Federation Trust Credentials for verifying assertions from the IdP and signing requests to the IdP:

Property Description DataType Nullable Readonly
signing Key used for signing requests to the IdP SAML 2.0 Signing Credentials object TRUE FALSE
trust Object that contains information for verifying assertions from the IdP SAML 2.0 Trust Credentials object FALSE FALSE
SAML 2.0 Trust Credentials object

Federation Trust Credentials for verifying assertions from the IdP:

Property Description DataType Nullable Readonly MinLength MaxLength Validation
audience URI that identifies the target Okta IdP instance (SP) for an <Assertion> String FALSE FALSE 1 1024 URI (opens new window)
issuer URI that identifies the issuer (IdP) of a SAML <SAMLResponse> message <Assertion> element String FALSE FALSE 1 1024 URI (opens new window)
kid Key ID reference to the IdP's X.509 signature certificate String FALSE FALSE 36 36 Valid IdP Key ID reference
{
  "protocol": {
    "type": "SAML2",
    "credentials": {
      "trust": {
        "issuer": "urn:example:idp",
        "audience": "https://www.okta.com/saml2/service-provider/spgv32vOnpdyeGSaiUpL",
        "kid": "your-key-id"
      }
    }
  }
}
SAML 2.0 Signing Credentials object

Determines the IdP Key Credential used to sign requests sent to the IdP:

Property Description DataType Nullable Readonly Validation
kid IdP Key Credential reference to the Okta X.509 signature certificate String FALSE FALSE Valid Signing Key ID reference
{
  "protocol": {
    "type": "SAML2",
    "credentials": {
      "signing": {
        "kid": "your-key-id"
      }
    }
  }
}
SAML 2.0 Settings object
Property Description DataType Nullable Readonly Default
nameFormat The name identifier format to use. See SAML 2.0 Name Identifier Formats. String TRUE FALSE urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
honorPersistentNameId Determines if the IdP should persist account linking when the incoming assertion NameID format is urn:oasis:names:tc:SAML:2.0:nameid-format:persistent Boolean TRUE FALSE FALSE
{
  "protocol": {
    "type": "SAML2",
    "settings": {
      "nameFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
      "honorPersistentNameId" : false
    }
  }
}
SAML 2.0 Name Identifier formats
Options
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
urn:oasis:names:tc:SAML:2.0:nameid-format:transient
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

OAuth 2.0 Protocol

Protocol settings for authentication using the OAuth 2.0 Authorization Code flow (opens new window):

Property Description DataType Nullable Readonly MinLength
credentials Client authentication credentials for an OAuth 2.0 Authorization Server (opens new window) Credentials object FALSE FALSE
endpoints Endpoint settings for the OAuth 2.0 Authorization Server OAuth 2.0 Endpoints object TRUE TRUE
scopes IdP-defined permission bundles to request delegated access from the User Array of String FALSE FALSE 1
type OAuth 2.0 Authorization Code flow (opens new window) OAUTH2 FALSE TRUE

Note: The Identity Provider type table lists the scopes that are supported for each Identity Provider.

{
  "protocol": {
    "type": "OAUTH2",
    "endpoints": {
      "authorization": {
        "url": "https://www.facebook.com/dialog/oauth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://graph.facebook.com/v2.5/oauth/access_token",
        "binding": "HTTP-POST"
      }
    },
    "scopes": [
      "public_profile",
      "email"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  }
}

OpenID Connect Protocol

Protocol settings for authentication using the OpenID Connect Protocol (opens new window):

Property Description DataType Nullable Readonly MinLength
algorithms Settings for signing authorization requests OIDC Algorithms object TRUE FALSE
credentials Client authentication credentials for an OAuth 2.0 Authorization Server (opens new window) Credentials object FALSE FALSE
endpoints Endpoint settings for the OAuth 2.0 Authorization Server OAuth 2.0 Endpoints object TRUE TRUE
scopes OpenID Connect and IdP-defined permission bundles to request delegated access from the User Array of String FALSE FALSE 1
type OpenID Connect Authorization Code flow (opens new window) OIDC FALSE TRUE

Note: The Identity Provider type table lists the scopes that are supported for each Identity Provider. The base openid scope is always required.

{
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://idp.example.com/authorize",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://idp.example.com/token",
        "binding": "HTTP-POST"
      },
      "userInfo": {
        "url": "https://idp.example.com/userinfo",
        "binding": "HTTP-REDIRECT"
      },
      "jwks": {
        "url": "https://idp.example.com/keys",
        "binding": "HTTP-REDIRECT"
      }
    },
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "HS256",
          "scope": "REQUEST"
        }
      }
    },
    "scopes": [
      "profile",
      "email",
      "openid"
    ],
    "credentials": {
      "client": {
        "client_id": "your-client-id",
        "client_secret": "your-client-secret"
      }
    }
  }
}
OIDC Algorithms object

The OIDC protocol supports the request algorithm and verification settings.

Property Description DataType Nullable Readonly
request Algorithm settings used to sign an authorization request OIDC Request Algorithm object FALSE FALSE
{
  "protocol": {
    "type": "OIDC",
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "HS256",
          "scope": "REQUEST"
        }
      }
    }
  }
}
OIDC Request Algorithm object

Algorithm settings for signing authorization requests sent to the IdP:

Property Description DataType Nullable Readonly
signature Algorithm settings used to sign an authorization request OIDC Signature Algorithm object FALSE FALSE
{
  "protocol": {
    "type": "OIDC",
    "algorithms": {
      "request": {
        "signature": {
          "algorithm": "HS256",
          "scope": "REQUEST"
        }
      }
    }
  }
}
OIDC request Signature Algorithm object

Signature Algorithm settings for signing authorization requests sent to the IdP:

Property Description DataType Nullable Readonly
algorithm The Signature Algorithm used when signing an authorization request HS256, HS384, HS512, RS256, RS384, or RS512 FALSE FALSE
scope Specifies whether to digitally sign an authorization request to the IdP REQUEST or NONE FALSE FALSE

Note: The algorithm property is ignored when you disable request signatures (scope set as NONE).

OAuth 2.0 and OpenID Connect endpoints object

The OAUTH2 and OIDC protocols support the authorization and token endpoints. Also, the OIDC protocol supports the userInfo and jwks endpoints.

The IdP Authorization Server (AS) endpoints are currently defined as part of the IdP provider and are read-only.

Property Description DataType Nullable Readonly
authorization IdP Authorization Server (AS) endpoint to request consent from the User and obtain an authorization code grant OAuth 2.0 Authorization Server Authorization Endpoint object TRUE TRUE
jwks Endpoint where the signer of the keys publishes its keys in a JWK Set OpenID Connect JWKs Endpoint object TRUE TRUE
token IdP Authorization Server (AS) endpoint to exchange the authorization code grant for an access token OAuth 2.0 Authorization Server Token Endpoint object TRUE TRUE
userInfo Protected resource endpoint that returns claims about the authenticated User OpenID Connect Userinfo Endpoint object TRUE TRUE
{
  "protocol": {
    "type": "OAUTH2",
    "endpoints": {
      "authorization": {
        "url": "https://www.facebook.com/dialog/oauth",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://graph.facebook.com/v2.5/oauth/access_token",
        "binding": "HTTP-POST"
      }
    }
  }
}
{
  "protocol": {
    "type": "OIDC",
    "endpoints": {
      "authorization": {
        "url": "https://idp.example.com/authorize",
        "binding": "HTTP-REDIRECT"
      },
      "token": {
        "url": "https://idp.example.com/token",
        "binding": "HTTP-POST"
      },
      "userInfo": {
        "url": "https://idp.example.com/userinfo",
        "binding": "HTTP-REDIRECT"
      },
      "jwks": {
        "url": "https://idp.example.com/keys",
        "binding": "HTTP-REDIRECT"
      }
    }
  }
}
OAuth 2.0 and OpenID Connect Credentials object

Client authentication credentials for an OAuth 2.0 Authorization Server (AS) (opens new window)

Property Description DataType Nullable Readonly
client Client infomation OAuth 2.0 And OpenID Connect Client Object FALSE FALSE
signing Information used to sign the request, currently only Apple IdP supports it Apple Client Signing Object TRUE FALSE
OAuth 2.0 and OpenID Connect Client object
Property Description DataType Nullable Readonly MinLength MaxLength
client_id Unique identifier (opens new window) issued by the AS for the Okta IdP instance String FALSE FALSE 1 1024
client_secret Client secret issued (opens new window) by the AS for the Okta IdP instance String TRUE (Only Nullable for Apple IdP) FALSE 1 1024
token_endpoint_auth_method Client authentication methods supported by the token endpoint. Methods supported: private_key_jwt String TRUE FALSE 1 1024
pkce_required Require Proof Key for Code Exchange (PKCE) for additional verification Boolean TRUE FALSE

Note: You must complete client registration with the IdP Authorization Server for your Okta IdP instance to obtain client credentials.

{
  "protocol": {
    "type": "OAUTH2",
    "credentials": {
      "client": {
        "client_id": "{{clientId}}",
        "client_secret": "{{clientSecret}}"
      }
    }
  }
}
{
  "protocol": {
    "type": "OIDC",
    "credentials": {
      "client": {
        "client_id": "{{clientId}}",
        "client_secret": "{{clientSecret}}"
      }
    }
  }
}
{
  "protocol": {
    "type": "OIDC",
    "credentials": {
      "client": {
        "client_id": "{{clientId}}",
        "token_endpoint_auth_method": "private_key_jwt"
      }
    }
  }
}
{
  "protocol": {
    "type": "OIDC",
    "credentials": {
      "client": {
        "client_id": "{{clientId}}",
        "token_endpoint_auth_method": "private_key_jwt",
        "pkce_required": "true"
      }
    }
  }
}
OpenID Connect Signing Credentials object

Determines the IdP Key Credential used to sign requests sent to the IdP. This object is used when token_endpoint_auth_method is private_key_jwt.

Property Description DataType Nullable Readonly Validation
kid IdP Key Credential reference to the Okta X.509 signature certificate. String TRUE FALSE Valid Signing Key ID reference
alg The algorithm used when generating the JWT from the private key for token endpoint authentication. RS256, RS384, RS512 FALSE FALSE Valid date type

Note: The kid parameter is required for an UPDATE request. For a CREATE request, it can be null.

{
  "protocol": {
    "type": "OIDC",
    "credentials": {
      "client": {
        "client_id": "{{clientId}}",
        "token_endpoint_auth_method": "private_key_jwt"
      },
      "signing":{
        "kid": "{{keyId}}",
        "alg": "RS256"
      }
    }
  }
}
Apple Client Signing object

The information is used to generate the secret JSON Web Token for the token requests to Apple IdP.

Property Description DataType Nullable Readonly MinLength MaxLength
privateKey The PKCS #8 encoded private key that you created for the client and downloaded from Apple String TRUE FALSE 1 1024
kid The Key ID that you obtained from Apple when you created the private key for the client String FALSE FALSE 1 1024
teamId The Team ID associated with your Apple developer account String FALSE FALSE 1 1024

Note: The privateKey property is required for a CREATE request. For an UPDATE request, it can be null and keeps the existing value if it's null. The privateKey property isn't returned for LIST and GET requests or UPDATE requests if it's null.

{
  "protocol": {
    "type": "OIDC",
    "credentials": {
      "signing": {
        "privateKey": "MIGTAgEAMBM........Cb9PnybCnzDv+3cWSGWqpAIsQQZ",
        "kid": "test key id",
        "teamId": "test team id"
      }
    }
  }
}

Note: The key is truncated for brevity.

MTLS Protocol

Protocol settings for the MTLS Protocol (opens new window):

Property Description DataType Nullable Readonly
credentials Description of the issuing cert MTLS Credentials Object FALSE FALSE
endpoints Location of authentication endpoint MTLS Endpoints Object FALSE FALSE
type The only supported value is MTLS String FALSE TRUE
{
  "type": "MTLS",
  "endpoints": {
    "sso": {
      "url": "https://{yourOktaDomain}.okta.com/login/cert"
    }
  },
  "credentials": {
    "trust": {
      "issuer": "CN=Test Smart Card, OU=Test OU, O=Test O, C=US",
      "audience": null,
      "kid":"45dec5ff-8cdc-48c0-85fe-a4869f1753dc",
      "revocation":"CRL",
      "revocationCacheLifetime":2880
    }
  }
}
MTLS Endpoints Object
Property Description DataType Nullable Readonly
sso IdP's SingleSignOnService endpoint MTLS SSO Endpoint Object FALSE TRUE
MTLS Single Sign-On (SSO) Endpoint Object

The Single Sign-On (SSO) endpoint is the IdP's SingleSignOnService endpoint:

Property Description DataType Nullable Readonly MinLength MaxLength Validation
url URL of binding-specific endpoint String FALSE TRUE 11 1014 RFC 3986 (opens new window)

Property Details

{
  "protocol": {
    "type": "MTLS",
    "endpoints": {
      "sso": {
        "url": "https://{yourOktaDomain}.okta.com/login/cert"
      }
    }
  }
}
MTLS Credentials Object

Certificate chain description for verifying assertions from the Smart Card.

Property Description DataType Nullable Readonly
trust Object containing information for verifying assertions from the IdP MTLS Trust Credentials Object FALSE FALSE
MTLS Trust Credentials Object

Certificate chain description for verifying assertions from the Smart Card.

Property Description DataType Nullable Readonly MinLength MaxLength Validation
audience not used String TRUE FALSE 1 1024 URI (opens new window)
issuer Description of the certificate issuer String FALSE FALSE 1 1024
kid Key ID reference to the IdP's X.509 signature certificate String FALSE FALSE 36 36 Valid IdP Key ID reference
revocation Mechanism to validate the certificate String FALSE FALSE 36 36 CRL
revocationCacheLifetime Time in minutes to cache the certificate revocation information Number FALSE FALSE 1 4320 from 1 minute to 72 hours
{
  "protocol": {
    "type": "MTLS",
    "credentials": {
      "trust": {
        "issuer": "CN=Test Smart Card, OU=Test OU, O=Test O, C=US",
        "audience": null,
        "kid":"45dec5ff-8cdc-48c0-85fe-a4869f1753dc",
        "revocation":"CRL",
        "revocationCacheLifetime":2880
      }
    }
  }
}

Policy Object

Property Description DataType Nullable Readonly Default
accountLink Policy rules to link an IdP User to an existing Okta User Account Link Policy object FALSE FALSE
mapAMRClaims Early Access Determines whether the IdP should map AMR claims from the IdP to the Okta session Boolean TRUE FALSE FALSE
maxClockSkew Maximum allowable clock skew when processing messages from the IdP Number FALSE FALSE
provisioning Policy rules to just-in-time (JIT) provision an IdP User as a new Okta User Provisioning Policy object FALSE FALSE
subject Policy rules to select the Okta sign-in identifier for the IdP User and determine matching rules Subject Policy object FALSE FALSE
{
  "policy": {
    "provisioning": {
      "action": "AUTO",
      "profileMaster": true,
      "groups": {
        "action": "NONE"
      },
      "conditions": {
        "deprovisioned": {
          "action": "NONE"
        },
        "suspended": {
          "action": "NONE"
        }
      }
    },
    "accountLink": {
      "filter": null,
      "action": "AUTO"
    },
    "subject": {
      "userNameTemplate": {
        "template": "idpuser.subjectNameId"
      },
      "filter": null,
      "matchType": "USERNAME"
    },
    "mapAMRClaims": false,
    "maxClockSkew": 120000
  }
}

IdP type policy actions

IdP Type User Provisioning Actions Group Provisioning Actions Account Link Actions Account Link Filters
SAML2 AUTO or DISABLED NONE, ASSIGN, APPEND, or SYNC AUTO, DISABLED groups
X509 DISABLED No support for JIT provisioning
[all social IdP types *] AUTO, DISABLED NONE or ASSIGN AUTO, DISABLED groups
Social IdP type policy actions *

All social IdP types (any IdP type that is not SAML2 or X509) support the same User Provisioning Actions, Group Provisioning Actions, Account Link Actions, and Account Link Filters.

Provisioning Policy object

Specifies the behavior for just-in-time (JIT) provisioning of an IdP User as a new Okta User and their Group memberships.

Property Description DataType Nullable Readonly
action Provisioning action for an IdP User during authentication User Provisioning Action Type FALSE FALSE
callout Deprecated Webhook settings for the CALLOUT action Callout object TRUE FALSE
conditions Conditional behaviors for an IdP User during authentication Provisioning Conditions object FALSE FALSE
groups Provisioning settings for a User's Group memberships Group Provisioning Policy object FALSE FALSE
profileMaster Determines if the IdP should act as a source of truth for User profile attributes Boolean FALSE FALSE
{
  "provisioning": {
    "action": "AUTO",
    "profileMaster": true,
    "groups": {
      "action": "SYNC",
      "sourceAttributeName": "Groups",
      "filter": [
        "00gak46y5hydV6NdM0g4"
      ]
    },
    "conditions": {
      "deprovisioned": {
        "action": "NONE"
      },
      "suspended": {
        "action": "NONE"
      }
    }
  }
}
IdP type Provisioning Policy actions

The follow provisioning actions are supported by each IdP provider:

Type User Provisioning Actions Group Provisioning Actions
SAML2 AUTO or DISABLED NONE, ASSIGN, APPEND, or SYNC
X509 DISABLED No support for JIT provisioning
[all social IdP types *] AUTO, DISABLED NONE or ASSIGN
Social IdP type provisioning policy actions

All social IdP types (any IdP type that is not SAML2 or X509) support the same User and Group Provisioning Actions.

User provisioning action type

Specifies the User provisioning action during authentication when an IdP User isn't linked to an existing Okta User.

Action Type Description
AUTO The IdP User profile is transformed through defined universal directory profile mappings to an Okta User profile and automatically provisioned as an Okta User.
CALLOUT Deprecated Okta calls out to an external web service during authentication to validate the IdP User profile, determine whether to provision a new Okta User, and define the resulting Okta User profile.
DISABLED Okta rejects the authentication request and skips provisioning of a new Okta User if the IdP User isn't linked to an existing Okta User.

Property details

  • To successfully provision a new Okta User, just-in-time (JIT) provisioning must be enabled in your organization security settings for AUTO or CALLOUT actions.
  • If the target username is not unique or the resulting Okta User profile is missing a required profile attribute, JIT provisioning may fail.
  • New Okta Users are provisioned with either a FEDERATION or SOCIAL authentication provider depending on the IdP type.
Group Provisioning Policy object
Property Description DataType Nullable Readonly MinLength MaxLength
action Provisioning action for the IdP User's Group memberships Group Provisioning Action Type FALSE FALSE
assignments List of OKTA_GROUP Group identifiers to add an IdP User as a member with the ASSIGN action Array of String (OKTA_GROUP IDs) TRUE FALSE
filter Allowlist of OKTA_GROUP Group identifiers for the APPEND or SYNC provisioning action Array of String (OKTA_GROUP IDs) TRUE FALSE
sourceAttributeName IdP User profile attribute name (case-insensitive) for an array value that contains Group memberships String TRUE FALSE 0 1024
{
  "groups": {
    "action": "ASSIGN",
    "assignments": [
      "00gak46y5hydV6NdM0g4"
    ]
  }
}
{
  "groups": {
    "action": "SYNC",
    "sourceAttributeName": "Groups",
    "filter": [
      "00gak46y5hydV6NdM0g4"
    ]
  }
}
Group provisioning action type

The Group provisioning action for an IdP User:

Action Description Existing OKTA_GROUP Memberships Existing APP_GROUP Memberships Existing BUILT_IN Memberships
APPEND Adds a User to any Group defined by the IdP as a value of the sourceAttributeName array that matches the name of the allow listed Group defined in the filter Unchanged Unchanged Unchanged
ASSIGN Assigns a User to Groups defined in the assignments array Unchanged Unchanged Unchanged
NONE Skips processing of Group memberships Unchanged Unchanged Unchanged
SYNC Group memberships are sourced by the IdP as a value of the sourceAttributeName array that matches the name of the Group defined in the filter Removed if not defined by the IdP in sourceAttributeName and matching name of the Group in filter Unchanged Unchanged

Note: Group provisioning action is processed independently from profile sourcing. You can sync Group memberships through SAML with profile sourcing disabled.

Group provisioning action examples

Organization Groups

ID Name Type
00g51vdPerxUiLarG0g4 Domain Users APP_GROUP
00gak46y5hydV6NdM0g4 Cloud Users OKTA_GROUP
00ggniobeT51fBl0B0g3 Everyone BUILT_IN
00gjg5lzfBpn62wuF0g3 MFA Users OKTA_GROUP
00glxpsrGUKMnSPss0g3 Enterprise IdP Users OKTA_GROUP

Existing Group memberships for an IdP User

ID Name Type
00g51vdPerxUiLarG0g4 Domain Users APP_GROUP
00gak46y5hydV6NdM0g4 Cloud Users OKTA_GROUP
00ggniobeT51fBl0B0g3 Everyone BUILT_IN

IdP Assertion

<saml:AttributeStatement
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <saml:Attribute Name="groups">
        <saml:AttributeValue xsi:type="xs:anyType">Enterprise IdP Users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:anyType">West Coast Users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:anyType">Cloud Users</saml:AttributeValue>
    </saml:Attribute>
</saml:AttributeStatement>

Provisioning policy action results

Action Source Attribute Name Assignments Filter Group Membership Results
APPEND Groups 00glxpsrGUKMnSPss0g3 Enterprise IdP Users, Cloud Users, Domain Users, & Everyone
ASSIGN 00gjg5lzfBpn62wuF0g3 MFA Users, Cloud Users, Domain Users, & Everyone
NONE Cloud Users, Domain Users, & Everyone
SYNC Groups 00glxpsrGUKMnSPss0g3 Enterprise IdP Users, Domain Users, & Everyone
Provisioning Conditions object
Property Description DataType Nullable Readonly
deprovisioned Behavior for a previously deprovisioned IdP User during authentication Deprovisioned Condition object FALSE FALSE
suspended Behavior for a previously suspended IdP User during authentication Suspended Condition object FALSE FALSE
{
  "deprovisioned": {
    "action": "NONE"
  },
  "suspended": {
    "action": "NONE"
  }
}
Deprovisioned Condition object
Property Description DataType Nullable Readonly
action Action for a previously deprovisioned IdP User during authentication Deprovisioned Action Type FALSE FALSE
{
  "action": "NONE"
}
Deprovisioned action type

Specifies the action during authentication when an IdP User is linked to a previously deprovisioned Okta User.

Action Type Description
NONE Take no action. If an IdP User that matches a previously deprovisioned Okta User attempts to authenticate, authentication fails.
REACTIVATE If an IdP User that matches a previously deprovisioned Okta User attempts to authenticate, reactivate the matching User in Okta and allow the authentication attempt to proceed.
Suspended Condition object
Property Description DataType Nullable Readonly
action Action for a previously suspended IdP User during authentication Suspended Action Type FALSE FALSE
{
  "action": "NONE"
}
Suspended action type

Specifies the action during authentication when an IdP User is linked to a previously suspended Okta User.

Action Type Description
NONE Take no action. If an IdP User that matches a previously suspended Okta User attempts to authenticate, authentication fails.
UNSUSPEND If an IdP User that matches a previously suspended Okta User attempts to authenticate, unsuspend the matching User in Okta and allow the authentication attempt to proceed.

Specifies the behavior for linking an IdP User to an existing Okta User.

Property Description DataType Nullable Readonly
action Specifies the account linking action for an IdP User Account Link Action Type FALSE FALSE
callout Deprecated Webhook settings for the CALLOUT action Callout object TRUE FALSE
filter Allowlist for link candidates Account Link Filter object TRUE FALSE
{
  "accountLink": {
    "filter": {
      "groups": {
        "include": [
          "00gjg5lzfBpn62wuF0g3"
        ]
      }
    },
    "action": "AUTO"
  }
}

The following Account Link actions are supported by each IdP provider:

Type Account Link Actions Account Link Filters
OIDC AUTO
SAML2 AUTO
[all social IdP types *] AUTO, DISABLED groups

All social IdP types (any IdP type that is not SAML2 or X509) support the same Account Link Actions and Filters.

The Account Link action for an IdP User during authentication:

Action Type Description
AUTO The IdP User is automatically linked to an Okta User when the transformed IdP User matches an existing Okta User according to subject match rules.
CALLOUT Deprecated Okta calls out to an external web service during authentication to validate the IdP User profile and determine whether to link the IdP User to an Okta User candidate.
DISABLED Okta never attempts to link the IdP User to an existing Okta User, but may still attempt to provision a new Okta User (See Provisioning Action Type.
{
  "accountLink": {
    "filter": {
      "groups": {
        "include": [
          "00gak46y5hydV6NdM0g4"
        ]
      }
    },
    "action": "AUTO"
  }
}

Specifies Group memberships to restrict which Users are available for account linking by an IdP.

Property Description DataType Nullable Readonly
groups Group memberships to determine link candidates Groups Account Link Filter object TRUE FALSE
{
  "filter": {
    "groups": {
      "include": [
        "00gjg5lzfBpn62wuF0g3"
      ]
    }
  }
}

Defines an allow list of Group membership to restrict which Users are available for account linking by an IdP.

Property Description DataType Nullable Readonly
include Specifies the allow list of Group identifiers to match against Array of String (Group IDs) TRUE FALSE

Note: Group memberships are restricted to type OKTA_GROUP.

{
  "groups": {
    "include": [
      "00gjg5lzfBpn62wuF0g3"
    ]
  }
}

Subject Policy object

Specifies the behavior for establishing, validating, and matching a username for an IdP User.

Property Description DataType Nullable Readonly MinLength MaxLength Validation
filter Optional regular expression pattern (opens new window) used to filter untrusted IdP usernames String TRUE FALSE 0 1024
matchAttribute Okta User profile attribute for matching a transformed IdP username. Only for matchType CUSTOM_ATTRIBUTE String TRUE FALSE See matchAttribute Validation
matchType Determines the Okta User profile attribute match conditions for account linking and authentication of the transformed IdP username USERNAME, EMAIL, USERNAME_OR_EMAIL or CUSTOM_ATTRIBUTE FALSE FALSE
userNameTemplate Okta Expression Language (EL) expression to generate or transform a unique username for the IdP User UserName Template object FALSE FALSE Okta EL Expression

matchAttribute Validation

The matchAttribute must be a valid Okta User profile attribute of one of the following types:

  • String (with no format or 'email' format only)
  • Integer
  • Number

Property details

  • Defining a regular expression pattern (opens new window) to filter untrusted IdP usernames for security purposes is highly recommended, especially if you have multiple IdPs connected to your organization. The filter prevents an IdP from issuing an assertion for any User including partners or directory Users in your Okta organization.

For example, the filter pattern (\S+@example\.com) allows only Users that have an @example.com username suffix and rejects assertions that have any other suffix such as @corp.example.com or @partner.com.

  • Only SAML2 and OIDC IdP providers support the filter property.
{
  "subject": {
    "userNameTemplate": {
      "template": "idpuser.subjectNameId"
    },
    "filter": null,
    "matchType": "USERNAME"
  }
}
UserName Template object
Property Description DataType Nullable Readonly MinLength MaxLength Validation
template Okta EL Expression to generate or transform a unique username for the IdP User String FALSE FALSE 9 1024 Okta EL Expression

Property details

  • IdP User profile attributes can be referenced with the idpuser prefix such as idpuser.subjectNameId.

  • You must define an IdP User profile attribute before it can be referenced in an Okta EL expression. To define an IdP User attribute policy, you may need to create a new IdP instance without a base profile property, edit the IdP User profile, and then update the IdP instance with an expression that references the IdP User profile attribute that you just created.

{
  "userNameTemplate": {
    "template": "idpuser.subjectNameId"
  }
}

OAuth 2.0 Authorization Server Authorization endpoint object

Endpoint for an OAuth 2.0 Authorization Server (AS) (opens new window).

The IdP Authorization Server (AS) endpoints are defined as part of the IdP provider and are read-only.

Property Description DataType Nullable Readonly MinLength Validation
binding HTTP binding used to send a request to the IdP Authorization Server (AS) endpoint HTTP-POST or HTTP-Redirect TRUE TRUE
url URL of the IdP Authorization Server (AS) authorization endpoint String TRUE TRUE 11 RFC 3986 (opens new window)
{
  "authorization": {
    "url": "https://idp.example.com/authorize",
    "binding": "HTTP-REDIRECT"
  }
}

OAuth 2.0 Authorization Server Token endpoint object

Endpoint for an OAuth 2.0 Authorization Server (AS) (opens new window)

The IdP Authorization Server (AS) endpoints are defined as part of the IdP provider and are read-only.

Property Description DataType Nullable Readonly MinLength Validation
binding HTTP binding used to send a request to the IdP Authorization Server (AS) endpoint HTTP-POST or HTTP-Redirect TRUE TRUE
url URL of the IdP Authorization Server (AS) token endpoint String TRUE TRUE 11 RFC 3986 (opens new window)
{
  "token": {
    "url": "https://idp.example.com/token",
    "binding": "HTTP-POST"
  }
}

OpenID Connect Userinfo endpoint object

Endpoint for getting identity information about the User. For more information on the /userinfo endpoint, see OpenID Connect (opens new window).

The OIDC endpoints are defined as part of the IdP provider and are read-only.

Property Description DataType Nullable Readonly MinLength Validation
binding HTTP binding used to send a request to the protected resource HTTP-POST or HTTP-Redirect TRUE TRUE
url URL of the resource server's /userinfo endpoint String TRUE TRUE 11 RFC 3986 (opens new window)
{
  "userInfo": {
    "url": "https://idp.example.com/userinfo",
    "binding": "HTTP-POST"
  }
}

OpenID Connect JWKs endpoint object

Endpoint for the JSON Web Key Set (JWKS) document. This document contains signing keys that are used to validate the signatures from the provider. For more information on JWKS, see JSON Web Key (opens new window).

The OIDC endpoints are defined as part of the IdP provider and are read-only.

Property Description DataType Nullable Readonly MinLength Validation
binding HTTP binding used to send the request HTTP-POST or HTTP-Redirect TRUE TRUE
url URL of the endpoint to the JWK Set String TRUE TRUE 11 RFC 3986 (opens new window)
{
  "jwks": {
    "url": "https://idp.example.com/keys",
    "binding": "HTTP-POST"
  }
}

Callout object

Note: This is a Deprecated feature.

Webhook settings for an IdP provisioning or account link Transaction:

Property Description DataType Nullable Readonly MinLength Validation
authorization HTTP authorization scheme and credentials to authenticate the webhook request Callout Authorization object TRUE FALSE
binding HTTP binding used to send the webhook HTTP-POST or HTTP-Redirect FALSE FALSE
url URL of binding-specific endpoint to send the webhook String FALSE FALSE 11 RFC 3986 (opens new window)
{
  "callout": {
    "url": "https://app.example.com",
    "binding": "HTTP-POST",
    "authorization": {
      "basic": {
        "username": "00ugr7Wf8PoSmPXbS0g3",
        "password": "00065EmIVWf7ln0HcVQNy9T_I7qS8rhjujc1hKHaoW"
      }
    }
  }
}
Callout Authorization object

Webhook authorization settings for an IdP provisioning or account link Transaction:

Property Description DataType Nullable Readonly
basic HTTP Basic Authorization Scheme Basic Authorization Scheme FALSE FALSE
bearer HTTP Bearer Authorization Scheme Bearer Authorization Scheme FALSE FALSE
custom Custom key/value HTTP headers Object FALSE FALSE

Property details

  • A null value specifies that no authorization scheme is used for a callout.
  • Authorization schemes are mutually exclusive. Specify a single scheme per callout.
Basic Authorization scheme
Property Description DataType Nullable Readonly
username unique identifier for the service account String FALSE FALSE
password service account password String FALSE FALSE
{
  "authorization": {
    "basic": {
      "username": "00ugr7Wf8PoSmPXbS0g3",
      "password": "00065EmIVWf7ln0HcVQNy9T_I7qS8rhjujc1hKHaoW"
    }
  }
}
Bearer Authorization scheme
Property Description DataType Nullable Readonly
token bearer token value String FALSE FALSE
{
  "authorization": {
    "bearer": {
      "token": "00065EmIVWf7ln0HcVQNy9T_I7qS8rhjujc1hKHaoW"
    }
  }
}

Specifies link relationships. See Web Linking (opens new window) available for the IdP using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and lifecycle operations and is read-only.

Link Relation Type Description
acs SAML 2.0 Assertion Consumer Service URL for the Okta SP
authorize OAuth 2.0 authorization endpoint for the IdP OAuth 2.0 Authorization Code flow (opens new window)
clientRedirectUri Redirect URI for the OAuth 2.0 Authorization Code flow (opens new window)
metadata Federation metadata document for the IdP (for example: SAML 2.0 Metadata)
self The primary URL for the IdP
users IdP Users

Identity Provider Transaction object

Note: This is a Deprecated feature.

The Identity Provider Transaction object represents an account link or just-in-time (JIT) provisioning Transaction.

Example

{
  "id": "satvklBYyJmwa6qOg0g3",
  "status": "ACCOUNT_JIT",
  "expiresAt": "2016-01-03T23:52:58.000Z",
  "created": "2016-01-03T23:44:38.000Z",
  "idp": {
    "id": "0oabmluDNh2JZi8lt0g4",
    "name": "Facebook",
    "type": "FACEBOOK"
  },
  "context": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko)
        Chrome/47.0.2526.106 Safari/537.36",
    "ipAddress": "54.197.192.167"
  },
  "_links": {
    "source": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/source"
    },
    "target": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/target"
    },
    "cancel": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/cancel",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    },
    "provision": {
      "href": "https://{yourOktaDomain}/api/v1/idps/tx/satvklBYyJmwa6qOg0g3/lifecycle/provision",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Identity Provider Transaction attributes

All IdP Transactions have the following properties:

Property Description DataType Nullable Unique Readonly
_embedded Embedded resources related to the Transaction JSON HAL (opens new window) TRUE FALSE TRUE
_links Discoverable resources related to the Transaction JSON HAL (opens new window) TRUE FALSE TRUE
context Optional authentication context for the Transaction Context object FALSE FALSE TRUE
created Timestamp when the Transaction was created Date FALSE FALSE TRUE
expiresAt Timestamp when the Transaction expires Date FALSE FALSE TRUE
id Unique key for the Transaction String FALSE TRUE TRUE
idp Identity Provider for an authenticated User IdP Authority object FALSE FALSE TRUE
sessionToken Ephemeral one-time token used to bootstrap an Okta session String TRUE FALSE TRUE
status Status of the Transaction ACCOUNT_JIT, ACCOUNT_LINK or SUCCESS FALSE FALSE TRUE

Note: The sessionToken is only available for completed transactions with the SUCCESS status.

Identity Provider Authority object

Metadata about the IdP that authenticated the User:

Property Description DataType Nullable Unique Readonly
id Unique key for the IdP String FALSE TRUE TRUE
name Unique name for the IdP String FALSE FALSE TRUE
type Type of IdP Identity Provider Type FALSE FALSE TRUE
{
  "idp": {
    "id": "0oabmluDNh2JZi8lt0g4",
    "name": "Facebook",
    "type": "FACEBOOK"
  }
}

Identity Provider Transaction Context object

Additional Context that describes the HTTP client for the Transaction:

Property Description DataType Nullable Unique Readonly
ipAddress Client IP Address for the Transaction String FALSE FALSE TRUE
userAgent HTTP User Agent string for the Transaction String FALSE FALSE TRUE
{
  "context": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko)
        Chrome/47.0.2526.106 Safari/537.36",
    "ipAddress": "54.197.192.167"
  }
}

Specifies link relationships. See Web Linking (opens new window) available for the IdP Transaction using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and lifecycle operations and is read-only.

Link Relation Type Description
cancel Cancels the Transaction
next Completes the Transaction
provision Lifecycle operation to just-in-time provision a new Okta User for the IdP User
source IdP User for the Transaction
target Transformed Okta User profile for the Transaction through UD Profile Mappings for the IdP
users Okta User candidates for the account link Transaction that match the IdP's account link policy and subject policy

Identity Provider Key Credential object

The IdP Key Credential object defines a JSON Web Key (opens new window) for a signature or encryption credential for an IdP.

Example

{
  "kid": "your-key-id",
  "created": "2016-01-03T18:15:47.000Z",
  "lastUpdated": "2016-01-03T18:15:47.000Z",
  "e": "65537",
  "n": "101438407598598116085679865987760095721749307901605456708912786847324207000576780508113360584
        555007890315805735307890113536927352312915634368993759211767770602174860126854831344273970871
        509573365292777620005537635317282520456901584213746937262823585533063042033441296629204165064
        680610660631365266976782082747",
  "kty": "RSA",
  "use": "sig",
  "x5c": [
    "MIIDnjCCAoagAwIBAgIGAVG3MN+PMA0GCSqGSIb3DQEBBQUAMIGPMQswCQYDVQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5p
     YTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEUMBIGA1UECwwLU1NPUHJvdmlkZXIxEDAOBgNVBAMM
     B2V4YW1wbGUxHDAaBgkqhkiG9w0BCQEWDWluZm9Ab2t0YS5jb20wHhcNMTUxMjE4MjIyMjMyWhcNMjUxMjE4MjIyMzMyWjCB
     jzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNVBAoMBE9r
     dGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRAwDgYDVQQDDAdleGFtcGxlMRwwGgYJKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29t
     MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtcnyvuVCrsFEKCwHDenS3Ocjed8eWDv3zLtD2K/iZfE8BMj2wpTf
     n6Ry8zCYey3mWlKdxIybnV9amrujGRnE0ab6Q16v9D6RlFQLOG6dwqoRKuZy33Uyg8PGdEudZjGbWuKCqqXEp+UKALJHV+k4
     wWeVH8g5d1n3KyR2TVajVJpCrPhLFmq1Il4G/IUnPe4MvjXqB6CpKkog1+ThWsItPRJPAM+RweFHXq7KfChXsYE7Mmfuly8s
     DQlvBmQyxZnFHVuiPfCvGHJjpvHy11YlHdOjfgqHRvZbmo30+y0X/oY/yV4YEJ00LL6eJWU4wi7ViY3HP6/VCdRjHoRdr5L/
     DwIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCzzhOFkvyYLNFj2WDcq1YqD4sBy1iCia9QpRH3rjQvMKDwQDYWbi6EdOX0TQ/I
     YR7UWGj+2pXd6v0t33lYtoKocp/4lUvT3tfBnWZ5KnObi+J2uY2teUqoYkASN7F+GRPVOuMVoVgm05ss8tuMb2dLc9vsx93s
     Dt+XlMTv/2qi5VPwaDtqduKkzwW9lUfn4xIMkTiVvCpe0X2HneD2Bpuao3/U8Rk0uiPfq6TooWaoW3kjsmErhEAs9bA7xuqo
     1KKY9CdHcFhkSsMhoeaZylZHtzbnoipUlQKSLMdJQiiYZQ0bYL83/Ta9fulr1EERICMFt3GUmtYaZZKHpWSfdJp9"
  ],
  "x5t#S256": "wzPVobIrveR1x-PCbjsFGNV-6zn7Rm9KuOWOG4Rk6jE"
}

Identity Provider Key Credential properties

IdP credential keys have the following properties:

Property Description DataType Nullable Unique Readonly
created Timestamp when the key was added to the key store Date FALSE FALSE TRUE
e The exponent value for the RSA public key String FALSE TRUE TRUE
kid Unique identifier for the key String FALSE TRUE TRUE
kty Identifies the cryptographic algorithm family used with the key (Supported value: RSA) String FALSE FALSE TRUE
lastUpdated Timestamp when the key was last updated Date FALSE FALSE TRUE
n The modulus value for the RSA public key String FALSE TRUE TRUE
use Intended use of the public key (Supported value: sig) String FALSE FALSE TRUE
x5c Base64-encoded X.509 certificate chain with DER encoding Array FALSE TRUE FALSE
x5t#S256 Base64url-encoded SHA-256 thumbprint of the DER encoding of an X.509 certificate String FALSE TRUE TRUE

Note: IdP signing keys are read-only.

Identity Provider User object

The Identity Provider User object represents a linked User and their IdP User profile.

Example

{
  "id": "00ulwodIu7wCfdiVR0g3",
  "externalId": "saml.jackson@example.com",
  "created": "2015-03-10T22:24:55.000Z",
  "lastUpdated": "2016-01-01T02:03:56.000Z",
  "profile": {
    "lastName": "Jackson",
    "subjectNameQualifier": "example.com",
    "subjectSpNameQualifier": "urn:federation:example",
    "authnContextClassRef": null,
    "subjectNameId": "saml.jackson@example.com",
    "subjectConfirmationAddress": null,
    "displayName": "Saml Jackson",
    "mobilePhone": "+1-415-555-5141",
    "email": "saml.jackson@example.com",
    "subjectNameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "firstName": "Saml",
    "subjectSpProvidedId": null,
    "subjectConfirmationMethod": null
  },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa1k5d68qR2954hb0g4/users/00ulwodIu7wCfdiVR0g3",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "idp": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oa1k5d68qR2954hb0g4"
    },
    "user": {
      "href": "https://{yourOktaDomain}/api/v1/users/00ulwodIu7wCfdiVR0g3"
    }
  }
}

Identity Provider User properties

All linked IdP Users have the following properties:

Property Description DataType Nullable Unique Readonly MaxLength
_embedded Embedded resources related to the IdP User JSON HAL (opens new window) TRUE FALSE TRUE
_links Discoverable resources related to the IdP User JSON HAL (opens new window) TRUE FALSE TRUE
created Timestamp when IdP User was created Date FALSE FALSE TRUE
externalId Unique IdP-specific identifier for the User String FALSE TRUE TRUE 512
id Unique key of the User String FALSE TRUE TRUE
lastUpdated Timestamp when the IdP User was last updated Date FALSE FALSE TRUE
profile IdP-specific profile for the User Identity Provider User Profile object FALSE FALSE TRUE

Identity Provider User Profile object

Identity Provider User profiles are IdP-specific but may be customized by the Profile Editor in the Admin Console.

IdP Profile Editor UI

Note: Okta variable names have reserved characters that may conflict with the name of an IdP assertion attribute. You can use the External name to define the attribute name as defined in an IdP assertion such as a SAML attribute name.

IdP Profile Editor Attribute Modal UI

Example Profile object

{
  "profile": {
    "lastName": "Jackson",
    "subjectNameQualifier": "example.com",
    "subjectSpNameQualifier": "urn:federation:example",
    "authnContextClassRef": null,
    "subjectNameId": "saml.jackson@example.com",
    "subjectConfirmationAddress": null,
    "displayName": "Saml Jackson",
    "mobilePhone": "+1-415-555-5141",
    "email": "saml.jackson@example.com",
    "subjectNameFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "firstName": "Saml",
    "subjectSpProvidedId": null,
    "subjectConfirmationMethod": null
  }
}

Specifies link relationships. See Web Linking (opens new window) available for the IdP User using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and lifecycle operations and is read-only.

Link Relation Type Description
idp The IdP that issued the identity
self The primary URL for the IdP User
users The linked Okta User

Identity Provider CSR object

The CSR object for the IdP defines a CSR for a signature or decryption credential for an IdP.

Example

{
  "id": "h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
  "created": "2017-03-28T01:11:10.000Z",
  "csr": "MIIC4DCCAcgCAQAwcTELMAkGA1UEBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xEzARBgNVBAoMCk9rdGEsIEluYy4xDDAKBgNVBAsMA0RldjESMBAGA1UEAwwJU1AgSXNzdWVyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6m8jHVCr9/tKvvbFN59T4raoCs/78KRm4fSefHQOv1TKLXo4wTLbsqYWRWc5u0sd5orUMQgPQOyj3i6qh13mALY4BzrT057EG1BUNjGg29QgYlnOk2iX890e5BIDMQQEIKFrvOi2V8cLUkLvE2ydRn0VO1Q1frbUkYeStJYC5Api2JQsYRwa+1ZeDH1ITnIzUaugWhW2WB2lSnwZkenne5KtffxMPYVu+IhNRHoKaRA6Z51YNhMJIx17JM2hs/H4Ka3drk6kzDf7ofk/yBpb9yBWyU7CTSQhdoHidxqFprMDaT66W928t3AeOENHBuwn8c2K9WeGG+bELNyQRJVmawIDAQABoCowKAYJKoZIhvcNAQkOMRswGTAXBgNVHREEEDAOggxkZXYub2t0YS5jb20wDQYJKoZIhvcNAQELBQADggEBAA2hsVJRVM+A83X9MekjTnIbt19UNT8wX7wlE9jUKirWsxceLiZBpVGn9qfKhhVIpvdaIRSeoFYS2Kg/m1G6bCvjmZLcrQ5FcEBjZH2NKfNppGVnfC2ugtUkBtCB+UUzOhKhRKJtGugenKbP33zRWWIqnd2waF6Cy8TIuqQVPbwEDN9bCbAs7ND6CFYNguY7KYjWzQOeAR716eqpEEXuPYAS4nx/ty4ylonR8cv+gpq51rvq80A4k/36aoeM0Y6I4w64vhTfuvWW2UYFUD+/+y2FA2CSP4JfctySrf1s525v6fzTFZ3qZbB5OZQtP2b8xYWktMzywsxGKDoVDB4wkH4=",
  "kty": "RSA",
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50",
      "hints": {
        "allow": [
          "GET",
          "DELETE"
        ]
      }
    },
    "publish": {
      "href": "https://{yourOktaDomain}/api/v1/idps/0oad5lTSBOMUBOBVVQSC/credentials/csrs/h9zkutaSe7fZX0SwN1GqDApofgD1OW8g2B5l2azha50/lifecycle/publish",
      "hints": {
        "allow": [
          "POST"
        ]
      }
    }
  }
}

Identity Provider CSR properties

Property Description DataType Nullable Unique Readonly
_links Discoverable resources related to the CSR JSON HAL (opens new window) TRUE FALSE TRUE
created Timestamp when the CSR was created Date FALSE FALSE TRUE
csr Base64-encoded CSR in DER format String TRUE TRUE TRUE
id Unique identifier for the CSR String FALSE TRUE TRUE
kty Cryptographic algorithm family for the CSR's keypair String FALSE FALSE TRUE

Identity Provider Social Authentication Token object

The Social Authentication Token object provides the tokens and associated metadata provided by social providers during social authentication. However, Okta doesn't import all the User information from a social provider. If the app needs information that isn't imported, it can get a User token from this endpoint, and then make an API call to the social provider with the token to request the additional information.

Example

[{
  "id": "<unique token identifier>",
  "token": "JBTWGV22G4ZGKV3N",
  "tokenType" : "urn:ietf:params:oauth:token-type:access_token",
  "tokenAuthScheme": "Bearer",
  "expiresAt" : "2014-08-06T16:56:31.000Z",
  "scopes"     : [ "openid", "foo" ]
},
{
"id": "<unique token identifier>",
"token": "JBTWGV22G4ZJBRXJ",
"tokenType" : "urn:ietf:params:oauth:token-type:id_token",
"tokenAuthScheme": null
}]

Identity Provider Social Authentication Token properties

Property Description DataType Nullable Unique Readonly
expiresAt The date that the token expires Date TRUE FALSE TRUE
id Unique identifier for the token String FALSE TRUE TRUE
scopes The scopes that the token is good for Array of Strings FALSE FALSE TRUE
token The raw token String FALSE TRUE TRUE
tokenAuthScheme The token authentication scheme as defined by the social provider String FALSE FALSE TRUE
tokenType The type of token defined by the OAuth Token Exchange Spec (opens new window) String TRUE TRUE TRUE