This guide is designed for Partners who want to build products and tools that integrate with the Oyster platform, to be used by mutual customers. This guide will help you create a Developer App and authorize access on the Oyster API.

Create a Developer App

Oyster grants access to API resources based on OAuth2. To access the API, you must first create a Developer App. Individual customers may then grant API access to your Developer App via an Authorization URL.

You must have an account on Oyster to create a Developer App. You can create a Developer App in a Developer Sandbox for development purposes, and will need to then do the same in a production account before offering the integration to customers. You can find more information about requesting and using a Developer Sandbox in this guide. To create an Oyster production account, please sign up here and notify [email protected].

Follow these steps:

1. Log in to your account.

2. Choose to create a new Oyster Developer App in the Developer Tab.

3. You will then be prompted to fill in the information about your developer application.

   
   1. Name is the application name that customers will see when authorizing the application.
   2. Description will be shown to customers if you choose to list the application in the Oyster integration page.
   3. Redirect URL is the endpoint in your domain where users will be redirected after they have authorized this developer app on their account. This must be a publicly-accessible URL and start with https.
   4. Choose the appropriate scopes for your application. Don’t include unnecessary scopes as this might discourage customers from authorizing your application.

4. Once submitted, you will see a popup with the Client ID and Client secret.

   1. The Client ID will still be available in the Developer applications list after you submit the page.
   2. Make sure to copy the Client secret before submitting the page as this will not be visible in plain text again! If you misplace the Client secret, you will be able to regenerate a new one in the Developer applications list.
   

Authorize access

Your developer app must be authorized to access any customer data. Authorization must be granted by a Company Admin via the Oyster application.

1. Copy the Authorization URL for your developer app (provided on the Developer Applications page) and save this as a configuration setting along with your Client ID and client Secret.
2. When a customer wishes to connect your application to Oyster, you will need to redirect the user to the Authorization URL to authorize your developer app.
   1. You can provide additional context to the Authorization URL using the state param. e.g. https://app.oysterhr.com/oauth/authorize/a1B2c3D4?state=yourInternalId. This param will be passed through verbatim and returned to you in the subsequent redirect.
3. Once the user has granted access to your developer app, they will be redirected back to the your application via the redirect URL.
4. The redirect will include a code parameter, which is the Authorization code required by the next step to create an Access Token.
   1. The redirect will also include the state param if you included it in the original authorization.
5. By default, apps can only be authorized by the company that created them. If you are a partner who would like to offer your app to other customers, please contact [email protected].