Skip to content
Plune Plune Plune Docs

Save a company’s identity provider settings

PUT
/v1/companies/{id}/sso
 
curl --request PUT \
  --url https://beta-api.plune.ai/v1/companies/example/sso \
  --header 'Content-Type: application/json' \
  --cookie plune_session=<plune_session> \
  --data '{ "idpEntityId": "https://idp.example.com/entity", "idpSsoUrl": "https://idp.example.com/sso", "idpCerts": [ "-----BEGIN CERTIFICATE-----\nMIIC8DCCAdigAwIBAgIIa83dSIfL7OUwDQYJKoZIhvcNAQELBQAwODE2MDQGA1UE\nAwwtaWRwLmV4YW1wbGUuY29tIChQbHVuZSBkb2N1bWVudGF0aW9uIGV4YW1wbGUp\nMB4XDTI2MDEwMTAwMDAwMFoXDTQ1MTIyNzAwMDAwMFowODE2MDQGA1UEAwwtaWRw\nLmV4YW1wbGUuY29tIChQbHVuZSBkb2N1bWVudGF0aW9uIGV4YW1wbGUpMIIBIjAN\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAreuGfj5XYZ/QC8RMQdt/2hKSNwNZ\nF+0b3EGTN2Lr/o0MKPA9Ozqjs2oUNQ5/b6w9EPH190JlLb+FKQhrXjyor4WNvcZo\niYhkwdeEDuibUAd6ikwub37NYsVx/Y/XRux3H59Mfovsg2QYYljkJsR0Qp1KAc+2\nYFLRu5cJcyz1V2SBwI0AY99BWdi/ACNFfiQOAR4U1o8KnoXo6Hm5jZSZBxWS8Wl2\nqp4YeBsFY/uSA4QKPZ1ifjdYwjjUlfJUP0nAhtpMHD6oCz5+CLTn1cOB+75yeekA\n96LZr5tzp33PShbqKykQVpFC/Nf71u5jLjHvlvQ6tCf1/y/Oty2HT8pToQIDAQAB\nMA0GCSqGSIb3DQEBCwUAA4IBAQB7qf6Bzo54E1TzZWhtUNt8iosOBPEqM0zi8raf\nUo9gmOmnitsWegKIy1Ri6okX9JDPjXbxM+Ev7qDp3m9ioPNcwYJL4mE4vD5uCj8V\ngc3HcPGKm7kUSlfZidLVUXa0oH8LlHTh+1FbCCv2KXyVFF5f9YfcZ8eYet+zWEtA\ng/IueYChpHq0L5f0ZckLc47yeDbxJWs/voIKxwR9JFXMglHloHIwuYha2nKdXIza\nKUoFFR5AwCzCqY/qnEE5yRDzCLitoXsCu4vcpwTJynBRTtEdgMwfmQxnJ3KJ0dJx\npT8NlVkLznKwmfIjr32Qnb2etsZEbD1jRzAirS88v85sA47X\n-----END CERTIFICATE-----\n" ], "enabled": true, "jit": true, "defaultRole": "member" }'

Owner only. The provider’s fields are sent whole; the switches are left as they are when absent. enabled needs a verified domain; enforced needs it enabled and the owner’s own sign-in through the provider (409 sso_test_login_required until then): the owner keeps the email link as an audited emergency way in, and the application owner can switch the requirement off. Changing the provider’s entity id or address lifts the requirement. Every change is a row of the company’s log. 20 a minute a person.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

Request Body required

Section titled “Request Body required ”
Media type application/json
object
idpEntityId
required

The identity provider’s entity id (its Issuer).

string
<= 500 characters
idpSsoUrl
required

Its single sign-on address; https only.

string
<= 2000 characters
idpCerts
required

Its PUBLIC certificates, PEM or the base64 body alone. Send the old one with the new one while the provider rotates, then the new one alone. A private key is refused.

Array<string>
>= 1 items <= 5 items
enabled

Needs a verified domain.

boolean
enforced

Single sign-on required: needs it enabled, a verified domain, and the owner’s own sign-in through the provider.

boolean
defaultRole

What a person who signs in for the first time joins as. Never manager or owner.

string
Allowed values: member reader
jit

Add people of a verified domain to the company at their first sign-in. Off unless asked: then it only proves who they are, and the company lets in the members and the invited.

boolean
emailAttribute

The attribute that holds the address when it is not the NameID.

string
nullable
nameAttribute

The attribute that holds the display name; used only where the person has none.

string
nullable
signRequests

For a provider that demands signed requests: the server makes a key pair for the company (the private key is sealed and never returned). 503 when the server has no SSO_ENCRYPTION_KEY.

boolean
revokeTokens

With the requirement on after this save: also revoke every API token of the people on the verified domains, in the same transaction (default false: tokens made before stay valid). Recorded in the company’s log; the count is tokensRevoked in the answer.

boolean
Example 
{
  "idpEntityId": "https://idp.example.com/entity",
  "idpSsoUrl": "https://idp.example.com/sso",
  "idpCerts": [
    "-----BEGIN CERTIFICATE-----\nMIIC8DCCAdigAwIBAgIIa83dSIfL7OUwDQYJKoZIhvcNAQELBQAwODE2MDQGA1UE\nAwwtaWRwLmV4YW1wbGUuY29tIChQbHVuZSBkb2N1bWVudGF0aW9uIGV4YW1wbGUp\nMB4XDTI2MDEwMTAwMDAwMFoXDTQ1MTIyNzAwMDAwMFowODE2MDQGA1UEAwwtaWRw\nLmV4YW1wbGUuY29tIChQbHVuZSBkb2N1bWVudGF0aW9uIGV4YW1wbGUpMIIBIjAN\nBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAreuGfj5XYZ/QC8RMQdt/2hKSNwNZ\nF+0b3EGTN2Lr/o0MKPA9Ozqjs2oUNQ5/b6w9EPH190JlLb+FKQhrXjyor4WNvcZo\niYhkwdeEDuibUAd6ikwub37NYsVx/Y/XRux3H59Mfovsg2QYYljkJsR0Qp1KAc+2\nYFLRu5cJcyz1V2SBwI0AY99BWdi/ACNFfiQOAR4U1o8KnoXo6Hm5jZSZBxWS8Wl2\nqp4YeBsFY/uSA4QKPZ1ifjdYwjjUlfJUP0nAhtpMHD6oCz5+CLTn1cOB+75yeekA\n96LZr5tzp33PShbqKykQVpFC/Nf71u5jLjHvlvQ6tCf1/y/Oty2HT8pToQIDAQAB\nMA0GCSqGSIb3DQEBCwUAA4IBAQB7qf6Bzo54E1TzZWhtUNt8iosOBPEqM0zi8raf\nUo9gmOmnitsWegKIy1Ri6okX9JDPjXbxM+Ev7qDp3m9ioPNcwYJL4mE4vD5uCj8V\ngc3HcPGKm7kUSlfZidLVUXa0oH8LlHTh+1FbCCv2KXyVFF5f9YfcZ8eYet+zWEtA\ng/IueYChpHq0L5f0ZckLc47yeDbxJWs/voIKxwR9JFXMglHloHIwuYha2nKdXIza\nKUoFFR5AwCzCqY/qnEE5yRDzCLitoXsCu4vcpwTJynBRTtEdgMwfmQxnJ3KJ0dJx\npT8NlVkLznKwmfIjr32Qnb2etsZEbD1jRzAirS88v85sA47X\n-----END CERTIFICATE-----\n"
  ],
  "enabled": true,
  "jit": true,
  "defaultRole": "member"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The settings after the save

Media type application/json

The owner reads everything below; a manager reads configured, enabled, enforced and, per domain, domain and verified - no value.

object
configured
required
boolean
sp

What to enter at the identity provider.

object
entityId
string
acsUrl
string
metadataUrl
string
startUrl

The bookmark for the provider’s application tile; null until a domain is verified.

string
nullable
idp
object
entityId
string
ssoUrl
string
certificates
Array<object>
object
pem
string
fingerprint256
string
subject
string
validFrom
string format: date-time
validTo
string format: date-time
enabled
required
boolean
enforced
required
boolean
defaultRole
string
Allowed values: member reader
jit
boolean
emailAttribute
string
nullable
nameAttribute
string
nullable
signRequests
boolean
spCertificate

The company’s public certificate for signed requests; there is no private key to read.

string
nullable
ownerSignedIn

The owner has signed in through this provider: what «required» waits for.

boolean
signingAvailable
boolean
tokensRevoked

Only in the answer to a save that sent revokeTokens: how many tokens it revoked (0 when the requirement is not on after it).

integer
domains
required
Array<object>
object
domain
required
string
verified
required
boolean
verifiedAt
required
string format: date-time
nullable
record
required

The DNS TXT record that proves the domain: put value in a TXT record at name, then ask for the verification.

object
type
required
string
Allowed values: TXT
name
required
string
value
required
string
Example 
{
  "defaultRole": "member",
  "domains": [
    {
      "domain": "acme.example",
      "record": {
        "type": "TXT",
        "name": "_plune-sso.acme.example",
        "value": "plune-sso-verification=Zt3b…"
      }
    }
  ]
}

400

Section titled “400 ”

A field is not valid, or a certificate is not a certificate

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

401

Section titled “401 ”

No / invalid session

403

Section titled “403 ”

The company does not have the saml option (code: tier_option_required, option: saml): a Team plan with the option, or Enterprise. Also: the caller is not the owner (or, for the read, a manager)

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

404

Section titled “404 ”

No such company, or the caller is not in it

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

409

Section titled “409 ”

sso_domain_required, sso_enabled_required or sso_test_login_required: what is missing first

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

429

Section titled “429 ”

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the window rolls over

503

Section titled “503 ”

Signed requests are not available on this server

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}