Authentication

📘

Partner Authentication

All 7shifts partners must authenticate using the OAuth 2.0 flow to use 7shifts API endpoints. Please refer to our OAuth guide that outlines how to implement this.

Companies and other non-partner integrators can authenticate to the 7shifts API by providing your API key in the request.

❗️

This recent API version does not support API keys

API keys only support V1 endpoints. If you wish to use any V2 endpoint you will need to acquire an OAuth client or an access token.

If you require access to V2 endpoints pleases contact [email protected] to acquire an Access Token. Access Token self administration coming soon.

Don't have an API key?

11771177

Generate an API key by first creating a 7shifts account. Once it's created, navigate to "Company Settings", then "API" and click "Generate".

Your API key carries many privileges, so be sure to keep them secret! Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

OAuth Clients

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 --request POST --url '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'

Refreshing a token

Tokens expire after 1 hour from creation. After they expire, you will need to create a new one using the create token process. A refresh token mechanism will be added in the future.

Access 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 you have acquired a token, you can use it make API requests.

All requests require two headers to be sent along. The Authorization Bearer header and an x-company-guid header.

The Authorization header includes a valid, unexpired token ISSUED_TOKEN. The x-company-guid header includes a GUID, this is issued to you during the company grant authorization process. The GUID is a 1:1 map to each company ID and a partner OAuth client.

To confirm your access token is valid, you can use the test endpoint https://api.7shifts.com/v2/whoami. If successful, it will return an identify_id in the payload.

curl --request GET --url 'https://api.7shifts.com/v2/whoami' \
--header 'x-company-guid: GUID' \
--header 'Authorization: Bearer ISSUED_TOKEN'

Below is an example of making a call to list all users in a company.

curl --request GET --url 'https://api.7shifts.com/v2/company/{COMPANY_ID}/users' \
--header 'x-company-guid: GUID' \
--header 'Authorization: Bearer ISSUED_TOKEN'