OAuth Authentication

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.

Requirements

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.

The OAuth flow

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.

Company grant process

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.

Company grant flow for administrators

Once a 7shifts admin has been sent to the aforementioned URL for granting access to your OAuth client, the flow looks as follows:

  1. If the admin is not already logged into 7shifts, they are shown the login screen so that they can login to 7shifts:
  1. 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:
  1. 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:
  1. 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.

  1. 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.

Creating a token

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'

Scopes

Notes

v1_access

Required for all V1 endpoint requests

companies:read
companies:write

Reading or mutating company object

departments:read
departments:write

Reading or mutating departments

locations:read
locations:write

Reading or mutating locations

roles:read
roles:write

Reading or mutating roles

users:read
users:write

Reading or mutating users

sales:read
sales:write

Reading or mutating sales

shifts:read
shifts:write

Reading or mutating shifts and schedule publishing

time_punches:read
time_punches:write

Reading or mutating time punches

events:read
events:write

Reading or mutating schedule events

Making API requests

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'

Did this page help you?