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 & 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 & 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
https://app.7shifts.com/generate_token?client_id=CLIENT_ID (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.
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 they have granted access, they will be redirected back to your callback URL with your unique authorization grant.
Demo mode - no redirect
During testing our company grant process will not redirect back to your callback URL by default. You will be shown a page with the GUID which you can copy. This is done to expedite testing and prototyping with tools such as Postman. If you wish to enable the callback URL please contact us to enable the callback URL redirect.
- 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 a identify_id in the payload.
curl --location --request POST '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 13 days ago