Getting Started with Embedded Sessions/SSO

Introduction

An Oyster Embedded Session allows you to securely transfer a user's basic information from your platform to Oyster, enabling functionalities like Single Sign-On (SSO) and pre-filled forms.

Prerequisites

1. Customer Account: Setup a customer account for your company: Create new account
2. Embedded Partner Features: Contact Oyster to enable Embedded Partner features on your customer account. Use the shared channel or reach out to your Oyster contact. Include your company dashboard link in the message.

General Overview

Here's a breakdown of the process (more detailed information in the Technical Details Section below):

1. User Action: Provide a call to action to users on your platform that will trigger an API call to Oyster.
2. API Request: The API request is to the Oyster Embedded Sessions endpoint with the user's basic information.
3. Unique Token: Oyster responds with a unique, one-time-use token.
4. User Redirect: Redirect the user to the dedicated /embedded/transfer endpoint.
5. Oyster uses the provided information and token to:
   1. Identify the user
   2. Automatically sign in the user into the Oyster Platform
   3. Direct the user to the desired page

Technical Details

Prerequisites

Please follow the Getting Started with Oyster API guide to help you get a Developer App setup.

Note: The sessions API is treated differently, therefore please use the customer instruction section of the guide.

While creating your Developer App, you should be able to obtain:

1. Client ID
2. Client secret
3. Authorization URL

You can save these configuration values for later use.

In the Node and Ruby sample apps, these values were saved as Environment Variables.

After creating your Developer App, follow the Authentication guide on how to generate API Access Tokens, Token expiration and how to Refresh Access Tokens to authenticate with the Oyster API.

After Authenticating your Developer App, you obtain:

1. access_token
2. refresh_token

We advise to store your client_id, access_token and refresh_token in your database.

Here are the Node and Ruby sample apps that include example implementations.

Create new user Session

Follow the API instructions to call the EmbeddedSessions API with the POST https://api.oysterhr.com/v0.1/embedded/sessions route. This endpoint is authorized using a Bearer Token, with the OAuth access_token generated and saved from previous steps.

The User information is sent as a JSON payload, here are the list of details:

Example using cURL: (Replace [ACCESS_TOKEN] with your access_token)

curl --request POST \
     --url https://api.oysterhr.com/v0.1/embedded/sessions \
     --header 'accept: application/json' \
     --header 'authorization: Bearer [ACCESS_TOKEN]' \
     --header 'content-type: application/json' \
     --data '
{
  "userEmail": "",
  "userName": "",
  "companyName": "",
  "companyEmailDomain": "",
  "companyTaxId": "",
  "userReference": "",
  "companyReference": "",
  "context": ""
}
'

with the payload:

The response would look something like:

{
  data: {
    token: 'unique_generated_token_here'
  }
}

Redirect to Oyster platform

Final step is to send user to oyster platform, use the token from previous step to redirect the user to this end point:

https://app.oysterhr.com/embedded/transfer?token={Place token from session api here}

💡

Redirect Token is used for SSO, thus special security measures are applied on it. This token will expire after 30 seconds, and it is one time use only.

Error handling

API Error messages are usually self-explanatory, like the Access token has expired, or it is invalid with the input parameters.

There is the 400 Bad request error that happens without a detailed error message, there are three main reasons you might get this error:

1. EmbeddedPartner features are not enabled for your company account on the oyster platform
2. Single Sign On from your platform is not enabled
3. If SSO was enabled and all was working fine until recently, something might have changed on our side

In all cases, please reach out to [email protected] to help you solve the problem.

Sample Applications

Sample applications in Ruby and Node are available here:

• Ruby (Ruby on Rails)
• Node (Express)