Getting Started with Oyster API
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.
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.
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 about 20 hours ago