Getting Started with Oyster API
This page will help you get started with Oyster. You'll be up and running in a jiffy!
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:
- Log in to your account.
- Choose to create a new Oyster Developer App in the Developer Tab.
- Redirect URL is the endpoint in your domain where users will be redirected after they have authorized this developer app on their account.
- N.B. this must be a publicly-accessible URL and start with
https
.
- N.B. this must be a publicly-accessible URL and start with
- Choose the appropriate scopes for your application. Don’t include unnecessary scopes as this might discourage customers from authorizing your application.
- *Make sure to copy the Client secret* before submitting the page as this will not be visible in plain text again!
- The associated Client ID will be available once you submit the page.
Customer instructions
Follow these steps:
- Log in to your account.
- Choose to create a new Oyster Developer App in the Developer Tab.
- Redirect URL can be any publicly-accessable URL that can be viewed in a browser without redirecting. For example
https://google.com
- N.B. this must start with
https
.
- N.B. this must start with
- 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.
- *Make sure to copy the Client secret* before submitting the page as this will not be visible in plain text again!
- 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.
Important: Partner apps need to be approved by us in order to be able to access customer data. By default, an app can only access data from the same company that owns it. Please email [email protected] with the details of your app in order to get it reviewed.
Partner instructions
- 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.
- 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.
- 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.
- N.B. You can provide additional context to the Authorization URL using the
- Once the user has granted access to your developer app, they will be redirected back to the your application via the redirect URL.
- The redirect will include a
code
parameter, which is the Authorization code required by the next step to create an Access Token.- N.B. the redirect will also include the
state
param if you included it in the original authorization.
- N.B. the redirect will also include the
Customer instructions
- Click on the Authorization URL for your developer app (provided on the Developer Applications page).
- In the new tab/window, authorize your Developer App to access your company’s data.
- This will redirect your browser to the Redirect URL specified in your developer app (e.g.
google.com
). - 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 thiscode
. 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!
Updated 11 days ago