All 7shifts partners must authenticate using the OAuth 2.0 flow to use 7shifts API endpoints. This guide will outline how to implement this flow.
If you are a new partner or don't have a 7shifts OAuth client yet, please reach out to [email protected] to start the setup process.
To expedite the OAuth client creation process, please have this information ready:
- Technical email contact (should be a valid email address not tied to a user)
- First & last name of the primary technical contact
- The official name for your company - used during authorization process
- A PNG image of your company logo - used during the authorization process
- A callback url - used to receive the company GUID after authorization granted
Once 7shifts has created an OAuth client for you, a client ID and a client secret will be shared with you. You must ensure that these credentials are stored safely, they cannot be recovered as losing them would require resetting the OAuth client and having to re-authorize your application to already integrated customers.
Upon completion of this guide, you will have implemented the OAuth 2.0 flow which will then be used for authentication when making consequent requests to the 7shifts API.
7shifts uses OAuths 2.0's authorization code grant flow to issue access tokens on behalf of users. The following diagram illustrates the OAuth flow based on the actions of the user (company administrator), partner (your app) and 7shifts.
For any mutual customers that wish to integrate your platform with 7shifts, a company administrator on their account will first need to allow access to their 7shifts company data for your OAuth client. This is usually completed by having the customer go to a certain URL that includes your OAuth client ID and allowing access to your OAuth client (also known as the 'Company Grant' flow).
The Authorization URL that the company administrator is redirected to on 7shifts is:
(Replace CLIENT_ID with your OAuth client ID).
It is highly recommended that you present this link to your customers on your platform's Integrations/Marketplace page.
To prevent CSRF attacks or to provide your own identifier during the generate company grant process, our protocols support the
state parameter. You can use this parameter to restore states to your application as it will be return back to your redirect url when a grant is created. The
state parameter is a string that you can encode whatever information you need.
The Authorization URL with a
Once a 7shifts admin has been sent to the aforementioned URL for granting access to your OAuth client, the flow looks as follows:
- If the admin is not already logged into 7shifts, they are shown the login screen so that they can login to 7shifts:
- If the admin is an administrator for multiple companies/accounts, then they are asked to choose the company that they wish to grant your OAuth client access to:
- Once they are logged in (and if they are an admin on multiple companies, have chosen the right account), they will be able to see your company's logo and choose to grant access. The logo is provided to 7shifts at the time of OAuth client creation:
- Once the "Grant Access" button is clicked, the grant GUID will be created. Depending on your OAuth client configuration, there are two methods to obtain the GUID.
Option 1 - No redirect URL configured
If you do not have a redirect URL configured on your OAuth client, the company will be shown a page with the GUID, which can be copied and provided back to you. It is recommended during testing to not setup a callback URL in your OAuth client in order to not have to setup a received handler for the GUID. Once you are ready to receive the GUID via the callback URL, contact 7shift support to have it configured.
Option 2 - Redirect URL configured
If you have a redirect URL configured on your OAuth client, upon pressing the "Grant Access" button, the page will be redirected to your redirect URL. The GUID and COMPANY_ID will be included in the URL after the #.
It is recommended that your server handle the redirect by providing a message indicating to the customer the process is complete, or navigating to additional configuration pages.
If you provided a
state parameter, it will be appended to the URL parameters.
- You can then use this unique grant (i.e. company GUID) to request an access token with the proper scopes to make API requests for that specific 7shifts company.
To make requests against an API, a bearer token must be issued that can be used for API calls. The token request requires a scope, the client ID, and the client secret. Bearer tokens expire after 1 hour. Only request the scopes you intend to use.
curl --location --request POST 'https://app.7shifts.com/oauth2/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=CLIENT_ID' \ --data-urlencode 'client_secret=CLIENT_SECRET' \ --data-urlencode 'scope=v1_access ADDITIONAL_SCOPES'
Required for all V1 endpoint requests
Reading or mutating company object
Reading or mutating departments
Reading or mutating locations
Reading or mutating roles
Reading or mutating users
Reading or mutating sales
Reading or mutating shifts and schedule publishing
Reading or mutating time punches
Reading or mutating schedule events
Once a bearer token has been issued, it can be used to make API requests.
All requests require two headers to be sent along. The Authorization Bearer header, with the token issued from the previous token request, and an x-company-guid header. This GUID ensures the request is being made for one specific company.
The GUID is issued to a partner when a company grant is authorized by an administrator of the account. The GUID is a 1:1 map to each company ID.
To confirm your access token is valid, you can use the test endpoint
/api/v2/whoami. If successful, it will return an identify_id in the payload.
curl --location --request GET 'https://api.7shifts.com/v2/whoami' \ --header 'x-company-guid: GUID' \ --header 'Authorization: Bearer ISSUED_TOKEN'
Once you have verified your OAuth authentication, you may start making API calls.
url --location --request GET 'https://api.7shifts.com/v1/users/12345' \ --header 'x-company-guid: GUID' \ --header 'Authorization: Bearer ISSUED_TOKEN'
Updated 1 day ago