Add an identity provider

OIDC (authorization code with PKCE) or SAML (SP-initiated, signed responses and assertions). Upstream metadata and keys are fetched by sso-worker through the hardened egress, within seconds and then every 6 hours.

POST

https://sso.ezghcloud.com/v1/organizations/{orgId}/sso/identity-providers

View as Markdown

Authorization

apiKeyoptionalHTTP
oauthoptionalHTTP
sessionCookieoptionalAPI key in cookie

Path parameters

orgIdstringrequired
format: uuid

Header parameters

Idempotency-Keyoptionalstring
Makes a retry safe: the same key and request get the stored response.

pattern: ^[\x21-\x7e]{1,200}$

Request bodyJSONrequired

namestringrequired
maxLength: 100
protocoloidcorsamlrequired
descriptionoptionalstring
maxLength: 1024
domainsoptionalarray ofstring
groupMappingsoptionalarray ofobject
2 properties
- groupIdstringrequired
  A hosted directory group.
  
  format: uuid
- idpGroupstringrequired
  The group's name at the identity provider, or * for everyone who signs in through it.
oidcoptionalobject
7 properties
- clientIdoptionalstring
- clientSecretoptionalstring | null
  Write-only; null removes it. Sealed at rest, never shown.
- emailClaimoptionalstring
- groupsClaimoptionalstring
- issueroptionalstring
  format: uri
- scopesoptionalarray ofstring
- tokenEndpointAuthMethodoptionalclient_secret_basicorclient_secret_postornone
samloptionalobject
4 properties
- emailAttributeoptionalstring
  Empty: the NameID (emailAddress format) or a common email attribute.
- groupsAttributeoptionalstring
- metadataUrloptionalstring | null
  format: uri
- metadataXmloptionalstring
  The IdP's metadata by value, instead of metadataUrl.
  
  maxLength: 262144
tagsoptionalmap ofstring

Returns

201

The identity provider.

JSON

createdAtstringrequired
format: date-time
descriptionstringrequired
directoryIdstringrequired
format: uuid
domainsarray ofstringrequired
The directory's domains routed here; each routes only while verified.
groupMappingsarray ofobjectrequired
2 properties
- groupIdstringrequired
  A hosted directory group.
  
  format: uuid
- idpGroupstringrequired
  The group's name at the identity provider, or * for everyone who signs in through it.
idstringrequired
format: uuid
metadataobjectrequired
3 properties
- errorstring | nullrequired
- fetchedAtstring | nullrequired
  format: date-time
- refreshRequestedAtstring | nullrequired
  format: date-time
namestringrequired
oidcIdpOidcornullrequired
2 variants
One of the following:
IdpOidc
View IdpOidc schema →
10 properties
clientIdstringrequired
clientSecretSetbooleanrequired
customDomainRedirectUrisarray ofstringrequired
The redirect URIs on the directory's active custom domains. Federation started on a custom domain comes back there, so register them upstream as well.

format: uri
discoveryobject | nullrequired
5 properties
authorizationEndpointstringrequired
idTokenSigningAlgsarray ofstringrequired
issuerstringrequired
jwksUristringrequired
tokenEndpointstringrequired
emailClaimstringrequired
groupsClaimstringrequired
issuerstringrequired
format: uri
redirectUristringrequired
Register this at the provider.

format: uri
scopesarray ofstringrequired
tokenEndpointAuthMethodclient_secret_basicorclient_secret_postornonerequired
null
organizationIdstringrequired
format: uuid
projectIdstring | nullrequired
protocoloidcorsamlrequired
provisioningobjectrequired
scim: a live directory SCIM token names this identity provider, so only provisioned users sign in; otherwise jit.
2 properties
- jitbooleanrequired
- scimbooleanrequired
regionstringrequired
resourceNamestringrequired
samlIdpSamlornullrequired
2 variants
One of the following:
IdpSaml
View IdpSaml schema →
5 properties
emailAttributestringrequired
Empty: the NameID (emailAddress format) or a common email attribute.

groupsAttributestringrequired
identityProviderobject | nullrequired
3 properties
certificatesarray ofobjectrequired
3 properties
notAfterstringrequired
format: date-time
sha256stringrequired
subjectstringrequired
entityIdstringrequired
ssoUrlstringrequired
metadataUrlstring | nullrequired
format: uri
serviceProviderobjectrequired
4 properties
acsUrlstringrequired
customDomainAcsUrlsarray ofstringrequired
The ACS URLs on the directory's active custom domains (the entity ID stays the same). Federation started on a custom domain posts back there, so register them upstream as well; the metadata lists them.

format: uri
entityIdstringrequired
metadataUrlstringrequired
null
slugstringrequired
statusstringrequired
tagsmap ofstringrequired
updatedAtstringrequired
format: date-time

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.