🚧

This page has been deprecated. Please see the new getting started page here.

Welcome to the documentation for the Oyster API! This guide is designed to help you get up and started using 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.

The setup instructions are slightly tailored depending on whether you are a customer or partner.

• Partner: you want to build products and tools that integrate with the Oyster platform, to be used by mutual customers.
• Customer: you want to use the Oyster API to directly interact with your own company data on the Oyster platform.

Partner instructions

You must have an account on Oyster to create a Developer App. If you do not already have an account, create an Oyster account or email [email protected] with your name, company name, and corporate email address to request a developer sandbox. To use the developer sandbox, you will follow the same instructions below but use the following sandbox URLs:

• For token generation - <https://api-sandbox.oysterhr.com/oauth2/token>
• For all other API calls - https://api-sandbox.oysterhr.com

Follow these steps:

1. Log in to your account.
2. Choose to create a new Oyster Developer App in the Developer Tab.
3. Redirect URL is the endpoint in your domain where users will be redirected after they have authorized this developer app on their account.
   1. N.B. 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.
5. *Make sure to copy the Client secret before submitting the page as this will not be visible in plain text again!
6. The associated Client ID will be available once you submit the page.

Customer instructions

Follow these steps:

1. Log in to your account.
2. Choose to create a new Oyster Developer App in the Developer Tab.
3. Redirect URL can be any publicly-accessible URL that can be viewed in a browser without redirecting. For example https://google.com
   1. N.B. this must start with https.
4. Choose the appropriate scopes for your application. Depending on your use case, you may not wish to grant full API access to create and update data.
5. *Make sure to copy the Client secret* before submitting the page as this will not be visible in plain text again!
6. The associated Client ID will be available once you submit the page.

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.

Partner instructions

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. N.B. 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. N.B. the redirect will also include the state param if you included it in the original authorization.

Customer instructions

1. Click on the Authorization URL for your developer app (provided on the Developer Applications page).
2. In the new tab/window, authorize your Developer App to access your company’s data.
3. This will redirect your browser to the Redirect URL specified in your developer app (e.g. google.com).
4. The redirect will include a code parameter, which is the Authorization code required by the next step to create an Access Token. Make sure to copy this code. You don’t need anything more from that browser window, so you can close it.

Alternatives

If you are a partner looking to integrate Oyster capabilities into your app for your users, please be sure to also check out the Oyster Web Components documentation. It provides a list of embeddable components designed to seamlessly empower your app with Oyster features.

Support

Need help at any time? Contact [email protected] with any questions!