Single Sign-On

API Reference

Overview

The Single Sign-On API has been modeled to meet the OAuth 2.0 framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow.


Step One: Direct the user to a WorkOS Authorization URL

There are two types of authorization URLs to initiate single sign-on; with a domain parameter:

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  domain={foo-corp.com}

and with a provider parameter:

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  provider=GoogleOAuth

It is common to use the domain parameter when authenticating a user by their domain. However the provider parameter exists so you may authenticate all users with same Connection. For example a "Sign in with Google" button generally does not take into account a user's domain and a provider=GoogleOAuth would be used.

When possible, the domain and provider parameters can be used together to customize the login experience. For example, the following authorization URL:

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  domain=workos.com&
  provider=GoogleOAuth

will generate the following "Sign in with Google" prompt:

A state parameter is also optional. If included, the exact state parameter will be provided when a user is redirected to your application, as detailed in Step Two below.

Authorization URL

file_copy
https://api.workos.com/sso/authorize?
  response_type=code&
  client_id={projectId}&
  redirect_uri={redirectURI}&
  domain={foo-corp.com}&
  state=dj1kUXc0dzlXZ1hjUQ==

Step Two: Receive the redirect from WorkOS

Once a user authorizes with their Identity Provider, we issue a redirect to your Redirect URI with a code parameter to use in Step Three. A state parameter will also be included if it was provided in Step One.

Redirect URI Request

file_copy
{redirectURI}?
  code=01E2RJ4C05B52KKZ8FSRDAP23J&
  state=dj1kUXc0dzlXZ1hjUQ==

To learn how to configure and setup a Redirect URI, visit our Redirect URI Guide.

Step Three: Request the Profile

Now you need to exchange the code value received in the previous step for both an access token, and the user's profile. To make this exchange, POST the code, along with the following application identification parameters, to the WorkOS /sso/token endpoint.

  • client_id: Your project's identifier. Can be found in the SSO Configuration page.
  • client_secret Your project's secret API key. Can be found in the API Keys page.
  • authorization_code: The exact code you received in Step Two.

Example Request

Profile Request

file_copy
curl -G --request POST \
--url https://api.workos.com/sso/token \
-d client_id="{projectId}", \
-d client_secret="{secretKey}", \
-d grant_type="authorization_code", \
-d code="01E2RJ4C05B52KKZ8FSRDAP23J"

Example Response

JSON

file_copy
{
  "access_token": "01DMEK0J53CVMC32CK5SE0KZ8Q",
  "profile": {
      "email": "todd@{foo-corp.com}",
      "first_name": "Todd",
      "id": "prof_01DMC79VCBZ0NY2099737PSVF1",
      "connection_type": "okta",
      "idp_id": "00u1a0ufowBJlzPlk357",
      "last_name": "Rundgren",
      "object": "profile",
      "workos_id": "d653fee6207ba8616ad0b2251b204e31"
  }
}

REST API

Authentication

The SSO REST API authenticates using your API key. Your team's API key is located in your Developer Dashboard.

API keys are passed using a Bearer token in the Authorization header.

Terminal

file_copy
Authorization: Bearer {secretKey}

Error Codes

WorkOS uses standard HTTP response codes to indicate the success or failure of your API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate failure, normally due to error caused by incorrect or missing request information (e.g. providing an incorrect API key).

Codes in the 5xx range indicate an error with WorkOS's servers.

Resource Endpoints:

  • GET /connections
  • GET /connections/:id

Retrieve a List of Connections

Get a complete list of organization connections.

  • Endpoint: /connections
  • HTTP Method: GET
  • Body: A paginated list of all organization connections
  • Response: 200 status code

The /connections endpoint accepts the following optional query parameters:

  • domain: Filter Connections by their associated domain.
  • connection_type: Filter Connections by their type. Valid values include ADFSSAML, AzureSAML, GoogleOAuth, OktaSAML, and OneLoginSAML.
  • limit: Upper limit on the number of Connections to return, between 1 and 100. The default value is 10.
  • before: A cursor to use for pagination. before is a Connection object ID that takes the form conn_* and defines your place in the paginated list of Connection objects. before will return all Connections created before the cursor's value ID.
  • after: A cursor to use for pagination. after is a Connection object ID that takes the form conn_* and defines your place in the paginated list of Connection objects. after will return all Connections created after the cursor's value ID.

Example Request

Terminal

file_copy
curl --request GET \
 --url https://api.workos.com/connections \
 --header "Authorization: Bearer {secretKey}"

Example Response

JSON

file_copy
{
  "data": [
    {
      "connection_type": "GoogleOAuth",
      "external_key": "GbQX1B6LWUYcsGiq6k20iCUMA",
      "id": "conn_01E4ZCR3C56J083X43JQXF3JK5",
      "name": "Foo Corp.",
      "oauth_redirect_uri": "http://foo-corp.com/sso/oauth/google/GbQX1B6LWUYcsGiq6k20iCUMA/callback",
      "oauth_uid": "453759831276-j0cue5069gf4l39u0idevk6ibk0clcli.apps.googleusercontent.com",
      "oauth_secret": "3gjDWvP3XGtS2hD4VMDwc-qh",
      "object": "connection",
      "saml_entity_id": null,
      "saml_idp_url": null,
      "saml_relying_party_trust_cert": null,
      "saml_x509_certs": null,
      "status": "linked"
    },
    {
      "connection_type": "OktaSAML",
      "external_key": "GbQX1B6LWUYcsGiq6k20iCUMA",
      "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
      "name": "Example Co.",
      "oauth_redirect_uri": null,
      "oauth_secret": null,
      "oauth_uid": null,
      "object": "connection",
      "saml_entity_id": "http://www.okta.com/ert31rg83inANNuT04x7",
      "saml_idp_url": "https://example-co.okta.com/app/exampleco-sso1337/ert31rg83inANNuT04x7/sso/saml",
      "saml_relying_party_trust_cert": null,
      "saml_x509_certs":  [
        "-----BEGIN CERTIFICATE-----
        MIICVjCCAb8CAg37MA0GCSqGSIb3DQEBBQUAMIGbMQswCQYDVQQGEwJKUDEOMAwG
        A1UECBMFVG9reW8xEDAOBgNVBAcTB0NodW8ta3UxETAPBgNVBAoTCEZyYW5rNERE
        MRgwFgYDVQQLEw9XZWJDZXJ0IFN1cHBvcnQxGDAWBgNVBAMTD0ZyYW5rNEREIFdl
        YiBDQTEjMCEGCSqGSIb3DQEJARYUc3VwcG9ydEBmcmFuazRkZC5jb20wHhcNMTIw
        ODIyMDUyNzIzWhcNMTcwODIxMDUyNzIzWjBKMQswCQYDVQQGEwJKUDEOMAwGA1UE
        CAwFVG9reW8xETAPBgNVBAoMCEZyYW5rNEREMRgwFgYDVQQDDA93d3cuZXhhbXBs
        ZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMYBBrx5PlP0WNI/ZdzD
        +6Pktmurn+F2kQYbtc7XQh8/LTBvCo+P6iZoLEmUA9e7EXLRxgU1CVqeAi7QcAn9
        MwBlc8ksFJHB0rtf9pmf8Oza9E0Bynlq/4/Kb1x+d+AyhL7oK9tQwB24uHOueHi1
        C/iVv8CSWKiYe6hzN1txYe8rAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAASPdjigJ
        kXCqKWpnZ/Oc75EUcMi6HztaW8abUMlYXPIgkV2F7YanHOB7K4f7OOLjiz8DTPFf
        jC9UeuErhaA/zzWi8ewMTFZW/WshOrm3fNvcMrMLKtH534JKvcdMg6qIdjTFINIr
        evnAhf0cwULaebn+lMs8Pdl7y37+sfluVok=
        -----END CERTIFICATE-----"
      ],
      "status": "linked"
    }
  ],
  "listMetadata": {
    "before": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
    "after": null
  }
}

Retrieve a Single Connection

Get details for a single organization connection.

  • Endpoint: /connection/:id
  • HTTP Method: GET
  • Body: a single connection object
  • Response: 200 status code

Example Request

Terminal

file_copy
curl --request GET \
--url https://api.workos.com/connections/conn_01E2NPPCT7XQ2MVVYDHWGK1WN4 \
--header "Authorization: Bearer {secretKey}"

Example Response

JSON

file_copy
{
  "connection_type": "OktaSAML",
  "external_key": "GbQX1B6LWUYcsGiq6k20iCUMA",
  "id": "conn_01E2NPPCT7XQ2MVVYDHWGK1WN4",
  "name": "Example Co.",
  "oauth_redirect_uri": null,
  "oauth_secret": null,
  "oauth_uid": null,
  "object": "connection",
  "saml_entity_id": "http://www.okta.com/ert31rg83inANNuT04x7",
  "saml_idp_url": "https://example-co.okta.com/app/exampleco-sso1337/ert31rg83inANNuT04x7/sso/saml",
  "saml_relying_party_trust_cert": null,
  "saml_x509_certs":  [
    "-----BEGIN CERTIFICATE-----
    MIICVjCCAb8CAg37MA0GCSqGSIb3DQEBBQUAMIGbMQswCQYDVQQGEwJKUDEOMAwG
    A1UECBMFVG9reW8xEDAOBgNVBAcTB0NodW8ta3UxETAPBgNVBAoTCEZyYW5rNERE
    MRgwFgYDVQQLEw9XZWJDZXJ0IFN1cHBvcnQxGDAWBgNVBAMTD0ZyYW5rNEREIFdl
    YiBDQTEjMCEGCSqGSIb3DQEJARYUc3VwcG9ydEBmcmFuazRkZC5jb20wHhcNMTIw
    ODIyMDUyNzIzWhcNMTcwODIxMDUyNzIzWjBKMQswCQYDVQQGEwJKUDEOMAwGA1UE
    CAwFVG9reW8xETAPBgNVBAoMCEZyYW5rNEREMRgwFgYDVQQDDA93d3cuZXhhbXBs
    ZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMYBBrx5PlP0WNI/ZdzD
    +6Pktmurn+F2kQYbtc7XQh8/LTBvCo+P6iZoLEmUA9e7EXLRxgU1CVqeAi7QcAn9
    MwBlc8ksFJHB0rtf9pmf8Oza9E0Bynlq/4/Kb1x+d+AyhL7oK9tQwB24uHOueHi1
    C/iVv8CSWKiYe6hzN1txYe8rAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAASPdjigJ
    kXCqKWpnZ/Oc75EUcMi6HztaW8abUMlYXPIgkV2F7YanHOB7K4f7OOLjiz8DTPFf
    jC9UeuErhaA/zzWi8ewMTFZW/WshOrm3fNvcMrMLKtH534JKvcdMg6qIdjTFINIr
    evnAhf0cwULaebn+lMs8Pdl7y37+sfluVok=
    -----END CERTIFICATE-----"
  ],
  "status": "linked"
}