SSO on Published Pages

Require visitors to log in through your organization's SAML identity provider (IdP), such as Okta, Microsoft Entra ID or Google Workspace, before they can see your published pages. This page shows how to set it up with the API. The same settings are in the Design Editor, under the hosting settings.

Setup has three steps:

1. Connect your identity provider. The result is an SSO config.
2. Find the hosting and the projects published to it.
3. Tell the hosting which projects require login.

Requirements

• An account on the Organization plan.
• A Vev hosting: your own domain on Vev hosting, or a Vev staging domain. SSO is not available on hostings where you host the files yourself.
• An API key with the write:sso and read:hosting scopes (see Authentication).

Your account key is in the response of GET https://api.vev.design/v2/user/accounts.

1. Connect your identity provider

Send the settings of your IdP. Use one of these three ways.

With a metadata URL (most IdPs have one):

curl -X POST https://api.vev.design/v2/accounts/[accountKey]/sso-configs \
  --header "x-vev-key: [your-key]" \
  --header "Content-Type: application/json" \
  --data '{"name": "Company login", "metadataURL": "https://idp.example.com/metadata.xml"}'

With the metadata XML. Escape the quotes and line breaks in the JSON string:

{
  "name": "Company login",
  "metadataXML": "<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://idp.example.com\">...</EntityDescriptor>"
}

With the IdP values, without metadata. x509Certificates takes one or more PEM certificates. Send two during a certificate rotation:

{
  "name": "Company login",
  "idpEntityId": "https://idp.example.com",
  "ssoURL": "https://idp.example.com/saml/sso",
  "x509Certificates": ["-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"]
}

The response is the SSO config:

{
  "success": true,
  "data": {
    "key": "[configKey]",
    "name": "Company login",
    "spEntityId": "saml.x[accountKey]",
    "acsUrl": "https://api.vev.page/saml-callback",
    "idpEntityId": "https://idp.example.com",
    "ssoURL": "https://idp.example.com/sso",
    "x509Certificates": ["-----BEGIN CERTIFICATE-----\n..."]
  }
}

Keep the key. You use it in step 3.

Register these two values in your IdP:

GET /v2/accounts/[accountKey]/sso-configs lists all SSO configs of the account.

2. Find the hosting and its projects

curl https://api.vev.design/v2/accounts/[accountKey]/hostings \
  --header "x-vev-key: [your-key]"

{
  "success": true,
  "data": [
    {
      "key": "[hostingKey]",
      "domain": "www.example.com",
      "pages": [
        { "url": "www.example.com/", "projectKey": "[homeProjectKey]" },
        { "url": "www.example.com/careers", "projectKey": "[careersProjectKey]" }
      ]
    }
  ]
}

The response above is shortened. You need the key of the hosting. To set SSO for single projects, you also need the projectKey of each project.

3. Choose which projects require login

The request has two fields. Both are optional.

Example: all projects require login

curl -X PUT https://api.vev.design/v2/hostings/[hostingKey]/sso \
  --header "x-vev-key: [your-key]" \
  --header "Content-Type: application/json" \
  --data '{"ssoConfig": "[configKey]"}'

{
  "success": true,
  "data": {
    "hostingKey": "[hostingKey]",
    "domain": "www.example.com",
    "ssoConfig": "[configKey]",
    "projects": {}
  }
}

Example: all projects require login, but the careers project is public

{
  "ssoConfig": "[configKey]",
  "projects": {
    "[careersProjectKey]": null
  }
}

Example: only the careers project requires login

{
  "projects": {
    "[careersProjectKey]": "[configKey]"
  }
}

All other projects on the hosting are public.

Example: one project uses a different identity provider

{
  "ssoConfig": "[employeesConfigKey]",
  "projects": {
    "[partnerProjectKey]": "[partnersConfigKey]"
  }
}

The change applies without a publish. It can take up to one minute before all visitors see it.

Change or turn off SSO

PUT replaces all SSO settings of the hosting. Fields that you do not send are cleared. Read the current settings first, change them, and send ssoConfig and projects back:

curl https://api.vev.design/v2/hostings/[hostingKey]/sso \
  --header "x-vev-key: [your-key]"

To turn off SSO, send an empty body. All projects on the hosting are then public:

curl -X PUT https://api.vev.design/v2/hostings/[hostingKey]/sso \
  --header "x-vev-key: [your-key]" \
  --header "Content-Type: application/json" \
  --data '{}'

Delete an SSO config

curl -X DELETE https://api.vev.design/v2/accounts/[accountKey]/sso-configs/[configKey] \
  --header "x-vev-key: [your-key]"

If a hosting uses the SSO config, the API answers 409 with the domains of those hostings. Remove the SSO config from those hostings first.

Errors

All endpoints are in the API Reference.